draft-ietf-netmod-rfc6087bis-07.txt   draft-ietf-netmod-rfc6087bis-08.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track July 7, 2016 Intended status: Standards Track September 1, 2016
Expires: January 8, 2017 Expires: March 5, 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-07 draft-ietf-netmod-rfc6087bis-08
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 January 8, 2017. This Internet-Draft will expire on March 5, 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
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
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6
2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 6
2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 7 3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 8
4. General Documentation Guidelines . . . . . . . . . . . . . . . 8 4. General Documentation Guidelines . . . . . . . . . . . . . . . 9
4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 9
4.1.1. Example Modules . . . . . . . . . . . . . . . . . . . 9 4.1.1. Example Modules . . . . . . . . . . . . . . . . . . . 10
4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 10
4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11
4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 11
4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 12
4.6. Security Considerations Section . . . . . . . . . . . . . 11 4.6. Security Considerations Section . . . . . . . . . . . . . 12
4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 13
4.7.1. Documents that Create a New Namespace . . . . . . . . 12 4.7.1. Documents that Create a New Namespace . . . . . . . . 13
4.7.2. Documents that Extend an Existing Namespace . . . . . 12 4.7.2. Documents that Extend an Existing Namespace . . . . . 13
4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 12 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 13
4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 14
4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 13 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 14
5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15
5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 15
5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 17
5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 16 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 17
5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 17 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 18
5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 18 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 19
5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 18 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 19
5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 19 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 20
5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 20 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 21
5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 21 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 22
5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 21 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 22
5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 22 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 23
5.8. Module Header, Meta, and Revision Statements . . . . . . . 23 5.8. Module Header, Meta, and Revision Statements . . . . . . . 24
5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 24 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 25
5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 25 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 26
5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 26 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 27
5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 26 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 27
5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 27 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 28
5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 28 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 29
5.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 28 5.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 30
5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 30 5.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 31
5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 30 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 32
5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 31 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 33
5.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 32 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 33
5.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 33 5.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 35
5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 33 5.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 35
5.16. Notification Definitions . . . . . . . . . . . . . . . . . 33 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 36
5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 34 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 36
5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 35 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 37
5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 35 5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 37
5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 35 5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 37
5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 35 5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 38
5.19.1. Conditional Augment Statements . . . . . . . . . . . . 36 5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 38
5.19.2. Conditionally Mandatory Data Definition Statements . . 36 5.19.1. Conditional Augment Statements . . . . . . . . . . . . 38
5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 37 5.19.2. Conditionally Mandatory Data Definition Statements . . 39
5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 38 5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 40
5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 39 5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 41
5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 40 5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 42
5.24. Performance Considerations . . . . . . . . . . . . . . . . 42 5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 43
5.25. Open Systems Considerations . . . . . . . . . . . . . . . 43 5.24. Performance Considerations . . . . . . . . . . . . . . . . 47
5.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 43 5.25. Open Systems Considerations . . . . . . . . . . . . . . . 47
5.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 43 5.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 48
5.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 43 5.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 48
5.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 44 5.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 48
5.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 44 5.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 48
5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 45 5.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 48
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 49
7. Security Considerations . . . . . . . . . . . . . . . . . . . 47 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51
7.1. Security Considerations Section Template . . . . . . . . . 47 7. Security Considerations . . . . . . . . . . . . . . . . . . . 52
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49 7.1. Security Considerations Section Template . . . . . . . . . 52
9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 50 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 55
10.1. Normative References . . . . . . . . . . . . . . . . . . . 52 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57
10.2. Informative References . . . . . . . . . . . . . . . . . . 53 10.1. Normative References . . . . . . . . . . . . . . . . . . . 57
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 54 10.2. Informative References . . . . . . . . . . . . . . . . . . 58
A.1. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 54 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 59
A.2. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 54 A.1. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.3. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 54 A.2. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.4. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 55 A.3. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.5. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 55 A.4. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 60
A.6. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 55 A.5. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 60
A.7. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 55 A.6. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 60
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 57 A.7. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 61
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 59 A.8. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 61
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 61 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 62
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 64
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 66
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 6, line 9 skipping to change at page 7, line 9
o YIN o YIN
Note that the term 'module' may be used as a generic term for a YANG Note that the term 'module' may be used as a generic term for a YANG
module or submodule. When describing properties that are specific to module or submodule. When describing properties that are specific to
submodules, the term 'submodule' is used instead. submodules, the term 'submodule' is used instead.
2.4. Terms 2.4. Terms
The following terms are used throughout this document: The following terms are used throughout this document:
o published: A stable release of a module or submodule, usually o published: A stable release of a module or submodule. For example
contained in an RFC. the "Request for Comments" described in section 2.1 of [RFC2026]
is considered a stable publication.
o unpublished: An unstable release of a module or submodule, usually o unpublished: An unstable release of a module or submodule. For
contained in an Internet-Draft. example the "Internet-Draft" described in section 2.2 of [RFC2026]
is considered an unstable publication that is a work-in-progess,
subject to change at any time.
o YANG fragment: A set of YANG statements that are not intended to
represent a complete YANG module or submodule. These statements
are not intended for actual use, except to provide an example of
YANG statement usage. The invalid syntax "..." is sometimes used
to indicate that additional YANG statements would be present in a
real YANG module.
3. YANG Tree Diagrams 3. YANG Tree Diagrams
YANG tree diagrams provide a concise representation of a YANG module YANG tree diagrams provide a concise representation of a YANG module
to help readers understand the module structure. to help readers understand the module structure.
The meaning of the symbols in YANG tree diagrams is as follows: The meaning of the symbols in YANG tree diagrams is as follows:
o Brackets "[" and "]" enclose list keys. o Brackets "[" and "]" enclose list keys.
skipping to change at page 9, line 29 skipping to change at page 10, 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
The <CODE BEGINS> convention SHOULD NOT be used for example modules The <CODE BEGINS> convention SHOULD be used for complete example
or YANG fragments, in order to make sure module extraction tools will modules, but not YANG fragments. This allows module extraction tools
ignore them. to ignore partial YANG modules that are not intended to be compiled.
An example module SHOULD be named using the term "example", followed An example module SHOULD be named using the term "example", followed
by a hyphen, followed by a descriptive name, e.g., "example-toaster". 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
skipping to change at page 10, line 25 skipping to change at page 11, line 25
| +--rw config-list* [key-name] | +--rw config-list* [key-name]
| +--rw key-name string | +--rw key-name string
| +--rw optional-parm? string | +--rw optional-parm? string
| +--rw mandatory-parm identityref | +--rw mandatory-parm identityref
| +--ro read-only-leaf string | +--ro read-only-leaf string
+--ro top-level-nonconfig-container +--ro top-level-nonconfig-container
+--ro nonconfig-list* [name] +--ro nonconfig-list* [name]
+--ro name string +--ro name string
+--ro type string +--ro type string
The 'pyang' compiler can be used to produce the tree diagram, using
the '-f tree' command line parameter.
If the YANG module is comprised of groupings only, then the tree
diagram SHOULD contain the groupings. The 'pyang' compiler can be
used to produce a tree diagram with groupings using the '-f tree
--tree-print-groupings" command line parameters.
If the YANG module contains notifications, then the tree diagram
SHOULD contain the notifications. If the YANG module contains RPC
statements, then the tree diagram SHOULD contain the RPC statements.
4.4. Narrative Sections 4.4. Narrative Sections
The narrative part MUST include an overview section that describes The narrative part MUST include an overview section that describes
the scope and field of application of the module(s) defined by the the scope and field of application of the module(s) defined by the
specification and that specifies the relationship (if any) of these specification and that specifies the relationship (if any) of these
modules to other standards, particularly to standards containing modules to other standards, particularly to standards containing
other YANG modules. The narrative part SHOULD include one or more other YANG modules. The narrative part SHOULD include one or more
sections to briefly describe the structure of the modules defined in sections to briefly describe the structure of the modules defined in
the specification. the specification.
skipping to change at page 11, line 25 skipping to change at page 12, line 36
4.6. Security Considerations Section 4.6. Security Considerations Section
Each specification that defines one or more modules MUST contain a Each specification that defines one or more modules MUST contain a
section that discusses security considerations relevant to those section that discusses security considerations relevant to those
modules. modules.
This section MUST be patterned after the latest approved template This section MUST be patterned after the latest approved template
(available at http://trac.tools.ietf.org/area/ops/trac/wiki/ (available at http://trac.tools.ietf.org/area/ops/trac/wiki/
yang-security-guidelines). Section 7.1 contains the security yang-security-guidelines). Section 7.1 contains the security
considerations template dated 2013-05-08. Authors MUST check the considerations template dated 2013-05-08. Authors MUST check the WEB
webpage at the URL listed above in case there is a more recent page at the URL listed above in case there is a more recent version
version available. available.
In particular: In particular:
o Writable data nodes that could be especially disruptive if abused o Writable data nodes that could be especially disruptive if abused
MUST be explicitly listed by name and the associated security MUST be explicitly listed by name and the associated security
risks MUST be explained. risks MUST be explained.
o Readable data nodes that contain especially sensitive information o Readable data nodes that contain especially sensitive information
or that raise significant privacy concerns MUST be explicitly or that raise significant privacy concerns MUST be explicitly
listed by name and the reasons for the sensitivity/privacy listed by name and the reasons for the sensitivity/privacy
skipping to change at page 24, line 16 skipping to change at page 25, line 16
reference statement. reference statement.
A revision statement MUST be present for each published version of A revision statement MUST be present for each published version of
the module. The revision statement MUST have a reference the module. The revision statement MUST have a reference
substatement. It MUST identify the published document that contains substatement. It MUST identify the published document that contains
the module. Modules are often extracted from their original the module. Modules are often extracted from their original
documents, and it is useful for developers and operators to know how documents, and it is useful for developers and operators to know how
to find the original source document in a consistent manner. The to find the original source document in a consistent manner. The
revision statement MAY have a description substatement. revision statement MAY have a description substatement.
Each new revision MUST include a revision date that is higher than It is not required to keep the full revision history of draft
any other revision date in the module. The revision date does not versions (e.g., modules contained within Internet-Drafts). That is,
need to be updated if the module contents do not change in the new within a sequence of draft versions, only the most recent revision
document revision. need be recorded in the module. However, whenever a new (i.e.
changed) version is made available (e.g., via a new version of an
It is acceptable to reuse the same revision statement within Internet-Draft), the revision date of that new version MUST be
unpublished versions (i.e., Internet-Drafts), but the revision date updated to a date later than that of the previous version.
MUST be updated to a higher value each time the Internet-Draft is re-
posted.
5.9. Namespace Assignments 5.9. Namespace Assignments
It is RECOMMENDED that only valid YANG modules be included in It is RECOMMENDED that only valid YANG modules be included in
documents, whether or not they are published yet. This allows: documents, whether or not they are published yet. This allows:
o the module to compile correctly instead of generating disruptive o the module to compile correctly instead of generating disruptive
fatal errors. fatal errors.
o early implementors to use the modules without picking a random o early implementors to use the modules without picking a random
skipping to change at page 25, line 35 skipping to change at page 26, line 33
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 data 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 sometimes useful to define separate top-
level containers for configuration and non-configuration data. level containers for configuration and non-configuration data. For
some existing top-level data nodes, configuration data was not in
scope, so only one container representing operational data was
created.
The number of top-level data nodes within a module SHOULD be The number of top-level data nodes within a module SHOULD be
minimized. It is often useful to retrieve related information within minimized. It is often useful to retrieve related information within
a single subtree. If data is too distributed, is becomes difficult a single subtree. If data is too distributed, is becomes difficult
to retrieve all at once. to retrieve all at once.
The names and data organization SHOULD reflect persistent The names and data organization SHOULD reflect persistent
information, such as the name of a protocol. The name of the working information, such as the name of a protocol. The name of the working
group SHOULD NOT be used because this may change over time. group SHOULD NOT be used because this may change over time.
skipping to change at page 30, line 5 skipping to change at page 31, line 37
type int32; type int32;
} }
Correct: Correct:
type union { type union {
type int32; type int32;
type string; type string;
} }
5.11.5. Empty and Boolean
YANG provides an "empty" data type, which has one value (i.e.,
present). The default is "not present", which is not actually a
value. When used within a list key, only one value can (and must)
exist for this key leaf. The type "empty" SHOULD NOT be used for a
key leaf since it is pointless.
There is really no difference between a leaf of type "empty" and a
leaf-list of type "empty". Both are limited to one instance. The
type "empty" SHOULD NOT be used for a leaf-list.
The advantage of using type "empty" instead of type "boolean" is that
the default (not present) does not take up any bytes in a
representation. The disadvantage is that the client may not be sure
if an empty leaf is missing because it was filtered somehow or not
implemented. The client may not have a complete and accurate schema
for the data returned by the server, and not be aware of the missing
leaf.
The YANG "boolean" data type provides two values ("true" and
"false"). When used within a list key, two entries can exist for
this key leaf. Default values are ignored for key leafs, but a
default statement is often used for plain boolean leafs. The
advantage of the "boolean" type is that the leaf or leaf-list has a
clear representation for both values. The default value is usually
not returned unless explicitly requested by the client, so no bytes
are used in a typical representation.
In general, the "boolean" data type SHOULD be used instead of the
"empty" data type, as shown in the example below:
Incorrect:
leaf flag1 {
type empty;
}
Correct:
leaf flag2 {
type boolean;
default false;
}
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 40, line 27 skipping to change at page 43, line 18
5.23. Operational Data 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 data. 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 data 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 data parameters are associated with the particular operational data parameters are associated with the particular
configuration object (or group of objects). configuration object(s).
In the simplest use-cases , there is no interaction between If possible, operational data SHOULD be combined with its associated
configuration data. This prevents duplication of key leafs and
ancestor nodes. It also prevents race conditions for retrieval of
dynamic entries, and allows configuration and operational data to be
retrieved together with minimal message overhead.
Not preferred:
list foo {
...
}
list foo-state {
config false;
...
}
Preferred:
list foo {
container foo-state {
config false;
...
}
}
If it is not possible to combine configuration and operational data,
then the keys used to represent list entries SHOULD be the same type.
The "leafref" data type SHOULD be used in operational data for key
leafs that have corresponding configuration instances. The
"require-instance" statement MAY be set to "false" (in YANG 1.1
modules only) to indicate instances are allowed in the operational
state that do not exist in the associated configuration data.
The following example shows the use of the "leafref" data type:
Not preferred:
list foo {
key name;
leaf name {
type string;
}
...
}
list foo-state {
key name;
config false;
leaf name {
type string;
}
...
}
Preferred:
list foo {
key name;
leaf name {
type string;
}
...
}
list foo-state {
key name;
config false;
leaf name {
type leafref {
path "/foo/name";
require-instance false;
}
}
...
}
In the simplest use-cases, there is no interaction between
configuration and operational data. For example, the arbitrary configuration and operational data. For example, the arbitrary
administrative name or sequence number assigned to an access control administrative name or sequence number assigned to an access control
rule. The configured value is always the value that is being used by rule. The configured value is always the value that is being used by
the system. 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.
skipping to change at page 53, line 12 skipping to change at page 58, line 12
Recommendation REC-xpath-19991116, November 1999, Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
10.2. Informative References 10.2. Informative References
[RFC-STYLE] [RFC-STYLE]
Braden, R., Ginoza, S., and A. Hagens, "RFC Document Braden, R., Ginoza, S., and A. Hagens, "RFC Document
Style", September 2009, Style", September 2009,
<http://www.rfc-editor.org/rfc-style-guide/rfc-style>. <http://www.rfc-editor.org/rfc-style-guide/rfc-style>.
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision
3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996,
<http://www.rfc-editor.org/info/rfc2026>.
[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.
skipping to change at page 54, line 9 skipping to change at page 59, 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. v06 to v07 A.1. v07 to v08
o changed CODE BEGINS guideline for example modules
o updated tree diagram guidelines
o clarified published and unpublished terms
o added section on Empty and Boolean data types
o clarified how to update the revision statement
o updated operational state guidelines
o added 'YANG fragment' to terminology section
A.2. v06 to v07
o update contact statement guideline o update contact statement guideline
o update example modules guidelines o update example modules guidelines
o add guidelines on top-level data nodes o add guidelines on top-level data nodes
o add guideline on use of NP containers o add guideline on use of NP containers
o added guidelines on union types o added guidelines on union types
o add guideline on deviations o add guideline on deviations
o added section on open systems considerations o added section on open systems considerations
o added guideline about definitions reserved for future use o added guideline about definitions reserved for future use
A.2. v05 to v06 A.3. v05 to v06
o Changed example 'my-module' to 'example-module' o Changed example 'my-module' to 'example-module'
o Added section Updating YANG Modules (Published vs. Unpublished) o Added section Updating YANG Modules (Published vs. Unpublished)
o Added Example Modules section o Added Example Modules section
o Added "<EXAMPLE BEGINS>" convention for full example modules o Added "<EXAMPLE BEGINS>" convention for full example modules
o Added section on using action vs. rpc o Added section on using action vs. rpc
o Changed term "operational state" to "operational data" o Changed term "operational state" to "operational data"
o Added section on YANG Data Node Constraints o Added section on YANG Data Node Constraints
o Added guidelines on using must vs. when statements o Added guidelines on using must vs. when statements
o Made ietf-foo module validate for I-D submission o Made ietf-foo module validate for I-D submission
skipping to change at page 54, line 47 skipping to change at page 60, line 14
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.3. v04 to v05 A.4. 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 55, line 22 skipping to change at page 60, line 36
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.4. v03 ot v04 A.5. 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.5. v02 to v03 A.6. 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.6. v01 to v02 A.7. v01 to v02
o Updated draft based on mailing list comments. o Updated draft based on mailing list comments.
A.7. v00 to v01 A.8. v00 to v01
All issues from the issue tracker have been addressed. All issues from the issue tracker have been addressed.
https://github.com/netmod-wg/rfc6087bis/issues https://github.com/netmod-wg/rfc6087bis/issues
o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules
can use an Informative reference to this RFC for tree diagrams. can use an Informative reference to this RFC for tree diagrams.
Updated guidelines to reference this RFC when tree diagrams are Updated guidelines to reference this RFC when tree diagrams are
used used
 End of changes. 23 change blocks. 
124 lines changed or deleted 290 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/