draft-ietf-netmod-rfc6087bis-08.txt   draft-ietf-netmod-rfc6087bis-09.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track September 1, 2016 Obsoletes: 6087 (if approved) October 25, 2016
Expires: March 5, 2017 Intended status: Informational
Expires: April 28, 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-08 draft-ietf-netmod-rfc6087bis-09
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) and RESTCONF protocol
data model modules. implementations that utilize YANG data model modules.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 March 5, 2017. This Internet-Draft will expire on April 28, 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 18 skipping to change at page 2, line 19
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6
2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 6 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 6
2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 8 3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 8
4. General Documentation Guidelines . . . . . . . . . . . . . . . 9 4. General Documentation Guidelines . . . . . . . . . . . . . . . 9
4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 9 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 9
4.1.1. Example Modules . . . . . . . . . . . . . . . . . . . 10 4.2. Code Components . . . . . . . . . . . . . . . . . . . . . 9
4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 10 4.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 10
4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11 4.3. Terminology Section . . . . . . . . . . . . . . . . . . . 10
4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 11 4.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11
4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 12 4.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 11
4.6. Security Considerations Section . . . . . . . . . . . . . 12 4.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12
4.7. IANA Considerations Section . . . . . . . . . . . . . . . 13 4.7. Security Considerations Section . . . . . . . . . . . . . 12
4.7.1. Documents that Create a New Namespace . . . . . . . . 13 4.8. IANA Considerations Section . . . . . . . . . . . . . . . 13
4.7.2. Documents that Extend an Existing Namespace . . . . . 13 4.8.1. Documents that Create a New Namespace . . . . . . . . 13
4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 13 4.8.2. Documents that Extend an Existing Namespace . . . . . 13
4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 14 4.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 13
4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 14 4.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 14
4.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 14
5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15
5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 15 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 15
5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 17 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 17
5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 17 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 17
5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 18 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 18
5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 19 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 19
5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 19 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 19
5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 20 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 20
skipping to change at page 3, line 40 skipping to change at page 3, line 42
5.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 48 5.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 48
5.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 48 5.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 48
5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 49 5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 49
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51
7. Security Considerations . . . . . . . . . . . . . . . . . . . 52 7. Security Considerations . . . . . . . . . . . . . . . . . . . 52
7.1. Security Considerations Section Template . . . . . . . . . 52 7.1. Security Considerations Section Template . . . . . . . . . 52
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54
9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 55 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 55
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57
10.1. Normative References . . . . . . . . . . . . . . . . . . . 57 10.1. Normative References . . . . . . . . . . . . . . . . . . . 57
10.2. Informative References . . . . . . . . . . . . . . . . . . 58 10.2. Informative References . . . . . . . . . . . . . . . . . . 57
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 59 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 59
A.1. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 59 A.1. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.2. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 59 A.2. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.3. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 59 A.3. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.4. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 60 A.4. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 60
A.5. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 60 A.5. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 60
A.6. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 60 A.6. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 60
A.7. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.7. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 61
A.8. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.8. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 61
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 62 A.9. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 61
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 64 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 63
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 66 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 65
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 67
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] and RESTCONF
of data models, which can be reused and extended over time. [I-D.ietf-netconf-restconf] requires a modular set 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 [RFC7950] data models. YANG is used to define
is used to define the data structures, protocol operations, and the data structures, protocol operations, and notification content
notification content used within a NETCONF server. A server that used within a NETCONF and/or RESTCONF server. A server that supports
supports a particular YANG module will support client NETCONF a particular YANG module will support client NETCONF and/or RESTCONF
operation requests, as indicated by the specific content defined in operation requests, as indicated by the specific content defined in
the YANG module. the YANG module.
This document is similar to the Structure of Management Information This document is similar to the Structure of Management Information
version 2 (SMIv2) usage guidelines specification [RFC4181] in intent version 2 (SMIv2) usage guidelines specification [RFC4181] in intent
and structure. However, since that document was written a decade and structure. However, since that document was written a decade
after SMIv2 modules had been in use, it was published as a 'Best after SMIv2 modules had been in use, it was published as a 'Best
Current Practice' (BCP). This document is not a BCP, but rather an Current Practice' (BCP). This document is not a BCP, but rather an
informational reference, intended to promote consistency in documents informational reference, intended to promote consistency in documents
containing YANG modules. containing YANG modules.
Many YANG constructs are defined as optional to use, such as the Many YANG constructs are defined as optional to use, such as the
description statement. However, in order to maximize description statement. However, in order to maximize
interoperability of NETCONF implementations utilizing YANG data interoperability of NETCONF and RESTCONF implementations utilizing
models, it is desirable to define a set of usage guidelines that may YANG data models, it is desirable to define a set of usage guidelines
require a higher level of compliance than the minimum level defined that may require a higher level of compliance than the minimum level
in the YANG specification. defined in the YANG specification.
In addition, YANG allows constructs such as infinite length In addition, YANG allows constructs such as infinite length
identifiers and string values, or top-level mandatory nodes, that a identifiers and string values, or top-level mandatory nodes, that a
compliant server is not required to support. Only constructs that compliant server is not required to support. Only constructs that
all servers are required to support can be used in IETF YANG modules. all servers are required to support can be used in IETF YANG modules.
This document defines usage guidelines related to the NETCONF This document defines usage guidelines related to the NETCONF
operations layer and NETCONF content layer, as defined in [RFC6241]. operations layer and NETCONF content layer, as defined in [RFC6241],
and the RESTCONF methods and RESTCONF resources, as defined in
[I-D.ietf-netconf-restconf],
These guidelines are intended to be used by authors and reviewers to These guidelines are intended to be used by authors and reviewers to
improve the readability and interoperability of published YANG data improve the readability and interoperability of published YANG data
models. models.
Note that this document is not a YANG tutorial and the reader is Note that this document is not a YANG tutorial and the reader is
expected to know the YANG data modeling language before using this expected to know the YANG data modeling language before using this
document. document.
2. Terminology 2. Terminology
skipping to change at page 6, line 33 skipping to change at page 6, line 33
o capabilities o capabilities
o client o client
o operation o operation
o server o server
2.3. YANG Terms 2.3. YANG Terms
The following terms are defined in [I-D.ietf-netmod-rfc6020bis] and The following terms are defined in [RFC7950] and are not redefined
are not redefined here: here:
o data node o data node
o module o module
o namespace o namespace
o submodule o submodule
o version o version
skipping to change at page 7, line 15 skipping to change at page 7, line 15
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. For example o published: A stable release of a module or submodule. For example
the "Request for Comments" described in section 2.1 of [RFC2026] the "Request for Comments" described in section 2.1 of [RFC2026]
is considered a stable publication. is considered a stable publication.
o unpublished: An unstable release of a module or submodule. For o unpublished: An unstable release of a module or submodule. For
example the "Internet-Draft" described in section 2.2 of [RFC2026] example the "Internet-Draft" described in section 2.2 of [RFC2026]
is considered an unstable publication that is a work-in-progess, is considered an unstable publication that is a work-in-progress,
subject to change at any time. subject to change at any time.
o YANG fragment: A set of YANG statements that are not intended to o YANG fragment: A set of YANG statements that are not intended to
represent a complete YANG module or submodule. These statements represent a complete YANG module or submodule. These statements
are not intended for actual use, except to provide an example of are not intended for actual use, except to provide an example of
YANG statement usage. The invalid syntax "..." is sometimes used YANG statement usage. The invalid syntax "..." is sometimes used
to indicate that additional YANG statements would be present in a to indicate that additional YANG statements would be present in a
real YANG module. real YANG module.
3. YANG Tree Diagrams 3. YANG Tree Diagrams
skipping to change at page 9, line 11 skipping to change at page 9, line 11
o Ellipsis ("...") stands for contents of subtrees that are not o Ellipsis ("...") stands for contents of subtrees that are not
shown. shown.
4. General Documentation Guidelines 4. General Documentation Guidelines
YANG data model modules under review are likely to be contained in YANG data model modules under review are likely to be contained in
Internet-Drafts. All guidelines for Internet-Draft authors MUST be Internet-Drafts. All guidelines for Internet-Draft authors MUST be
followed. The RFC Editor provides guidelines for authors of RFCs, followed. The RFC Editor provides guidelines for authors of RFCs,
which are first published as Internet-Drafts. These guidelines which are first published as Internet-Drafts. These guidelines
should be followed and are defined in [RFC2223] and updated in should be followed and are defined in [RFC7322] and updated in
[RFC5741] and "RFC Document Style" [RFC-STYLE]. [RFC7841] and "RFC Document Style" [RFC-STYLE].
The following sections MUST be present in an Internet-Draft The following sections MUST be present in an Internet-Draft
containing a module: containing a module:
o Narrative sections o Narrative sections
o Definitions section o Definitions section
o Security Considerations section o Security Considerations section
skipping to change at page 9, line 48 skipping to change at page 9, line 48
YANG fragments as well. 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/
4.2. Code Components
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 [RFC7950]. The following
[I-D.ietf-netmod-rfc6020bis]. The following example is for the 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@2016-03-20.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"; namespace "urn:ietf:params:xml:ns:yang:ietf-foo";
prefix "foo"; prefix "foo";
organization "..."; organization "...";
contact "..."; contact "...";
description "..."; description "...";
revision 2016-03-20 { revision 2016-03-20 {
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.2.1. Example Modules
The <CODE BEGINS> convention SHOULD be used for complete example The <CODE BEGINS> convention SHOULD be used for complete example
modules, but not YANG fragments. This allows module extraction tools modules, but not YANG fragments. This allows module extraction tools
to ignore partial YANG modules that are not intended to be compiled. 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.3. 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:
A simplified graphical representation of the data model is used in A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these diagrams is this document. The meaning of the symbols in these diagrams is
defined in [RFCXXXX]. defined in [RFCXXXX].
-- RFC Editor: Replace XXXX with RFC number and remove note -- RFC Editor: Replace XXXX with RFC number and remove note
4.3. Tree Diagrams 4.4. Tree Diagrams
YANG tree diagrams provide a concise representation of a YANG module, YANG tree diagrams provide a concise representation of a YANG module,
and SHOULD be included to help readers understand YANG module and SHOULD be included to help readers understand YANG module
structure. Tree diagrams MAY be split into sections to correspond to structure. Tree diagrams MAY be split into sections to correspond to
document structure. document structure.
The following example shows a simple YANG tree diagram: The following example shows a simple YANG tree diagram:
+--rw top-level-config-container +--rw top-level-config-container
| +--rw config-list* [key-name] | +--rw config-list* [key-name]
skipping to change at page 11, line 37 skipping to change at page 11, line 37
If the YANG module is comprised of groupings only, then the tree If the YANG module is comprised of groupings only, then the tree
diagram SHOULD contain the groupings. The 'pyang' compiler can be diagram SHOULD contain the groupings. The 'pyang' compiler can be
used to produce a tree diagram with groupings using the '-f tree used to produce a tree diagram with groupings using the '-f tree
--tree-print-groupings" command line parameters. --tree-print-groupings" command line parameters.
If the YANG module contains notifications, then the tree diagram If the YANG module contains notifications, then the tree diagram
SHOULD contain the notifications. If the YANG module contains RPC SHOULD contain the notifications. If the YANG module contains RPC
statements, then the tree diagram SHOULD contain the RPC statements. statements, then the tree diagram SHOULD contain the RPC statements.
4.4. Narrative Sections 4.5. 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.
If the module(s) defined by the specification imports definitions If the module(s) defined by the specification imports definitions
from other modules (except for those defined in the from other modules (except for those defined in the [RFC7950] or
[I-D.ietf-netmod-rfc6020bis] or [RFC6991] documents), or are always [RFC6991] documents), or are always implemented in conjunction with
implemented in conjunction with other modules, then those facts MUST other modules, then those facts MUST be noted in the overview
be noted in the overview section, as MUST be noted any special section, as MUST be noted any special interpretations of definitions
interpretations of definitions in other modules. in other modules.
4.5. Definitions Section 4.6. Definitions Section
This section contains the module(s) defined by the specification. This section contains the module(s) defined by the specification.
These modules SHOULD be written using the YANG syntax defined in These modules SHOULD be written using the YANG syntax defined in
[I-D.ietf-netmod-rfc6020bis]. YANG 1.0 [RFC6020] MAY be used if no [RFC7950]. YANG 1.0 [RFC6020] MAY be used if no YANG 1.1 constructs
YANG 1.1 constructs or semantics are needed in the module. or semantics are needed in the module.
A YIN syntax version of the module MAY also be present in the A YIN syntax version of the module MAY also be present in the
document. There MAY also be other types of modules present in the document. There MAY also be other types of modules present in the
document, such as SMIv2, which are not affected by these guidelines. document, such as SMIv2, which are not affected by these guidelines.
Note that all YANG statements within a YANG module are considered Note that all YANG statements within a YANG module are considered
normative, if the module itself is considered normative, and not an normative, if the module itself is considered normative, and not an
example module. The use of keywords defined in [RFC2119] apply to example module. The use of keywords defined in [RFC2119] apply to
YANG description statements in normative modules exactly as they YANG description statements in normative modules exactly as they
would in any other normative section. would in any other normative section.
Example YANG modules MUST NOT contain any normative text, including Example YANG modules MUST NOT contain any normative text, including
any reserved words from [RFC2119]. any reserved words from [RFC2119].
See Section 5 for guidelines on YANG usage. See Section 5 for guidelines on YANG usage.
4.6. Security Considerations Section 4.7. 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 WEB considerations template dated 2013-05-08. Authors MUST check the WEB
page at the URL listed above in case there is a more recent version page at the URL listed above in case there is a more recent version
skipping to change at page 13, line 7 skipping to change at page 13, line 7
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
concerns MUST be explained. concerns MUST be explained.
o Operations (i.e., YANG 'rpc' statements) that are potentially o Operations (i.e., YANG 'rpc' statements) that are potentially
harmful to system behavior or that raise significant privacy harmful to system behavior or that raise significant privacy
concerns MUST be explicitly listed by name and the reasons for the concerns MUST be explicitly listed by name and the reasons for the
sensitivity/privacy concerns MUST be explained. sensitivity/privacy concerns MUST be explained.
4.7. IANA Considerations Section 4.8. IANA Considerations Section
In order to comply with IESG policy as set forth in In order to comply with IESG policy as set forth in
http://www.ietf.org/id-info/checklist.html, every Internet-Draft that http://www.ietf.org/id-info/checklist.html, every Internet-Draft that
is submitted to the IESG for publication MUST contain an IANA is submitted to the IESG for publication MUST contain an IANA
Considerations section. The requirements for this section vary Considerations section. The requirements for this section vary
depending on what actions are required of the IANA. If there are no depending on what actions are required of the IANA. If there are no
IANA considerations applicable to the document, then the IANA IANA considerations applicable to the document, then the IANA
Considerations section stating that there are no actions is removed Considerations section stating that there are no actions is removed
by the RFC Editor before publication. Refer to the guidelines in by the RFC Editor before publication. Refer to the guidelines in
[RFC5226] for more details. [RFC5226] for more details.
4.7.1. Documents that Create a New Namespace 4.8.1. Documents that Create a New Namespace
If an Internet-Draft defines a new namespace that is to be If an Internet-Draft defines a new namespace that is to be
administered by the IANA, then the document MUST include an IANA administered by the IANA, then the document MUST include an IANA
Considerations section that specifies how the namespace is to be Considerations section that specifies how the namespace is to be
administered. administered.
Specifically, if any YANG module namespace statement value contained Specifically, if any YANG module namespace statement value contained
in the document is not already registered with IANA, then a new YANG in the document is not already registered with IANA, then a new YANG
Namespace registry entry MUST be requested from the IANA. The Namespace registry entry MUST be requested from the IANA. The
[I-D.ietf-netmod-rfc6020bis] specification includes the procedure for [RFC7950] specification includes the procedure for this purpose in
this purpose in its IANA Considerations section. its IANA Considerations section.
4.7.2. Documents that Extend an Existing Namespace 4.8.2. Documents that Extend an Existing Namespace
It is possible to extend an existing namespace using a YANG submodule It is possible to extend an existing namespace using a YANG submodule
that belongs to an existing module already administered by IANA. In that belongs to an existing module already administered by IANA. In
this case, the document containing the main module MUST be updated to this case, the document containing the main module MUST be updated to
use the latest revision of the submodule. use the latest revision of the submodule.
4.8. Reference Sections 4.9. Reference Sections
For every import or include statement that appears in a module For every import or include statement that appears in a module
contained in the specification, which identifies a module in a contained in the specification, which identifies a module in a
separate document, a corresponding normative reference to that separate document, a corresponding normative reference to that
document MUST appear in the Normative References section. The document MUST appear in the Normative References section. The
reference MUST correspond to the specific module version actually reference MUST correspond to the specific module version actually
used within the specification. used within the specification.
For every normative reference statement that appears in a module For every normative reference statement that appears in a module
contained in the specification, which identifies a separate document, contained in the specification, which identifies a separate document,
a corresponding normative reference to that document SHOULD appear in a corresponding normative reference to that document SHOULD appear in
the Normative References section. The reference SHOULD correspond to the Normative References section. The reference SHOULD correspond to
the specific document version actually used within the specification. the specific document version actually used within the specification.
If the reference statement identifies an informative reference, which If the reference statement identifies an informative reference, which
identifies a separate document, a corresponding informative reference identifies a separate document, a corresponding informative reference
to that document MAY appear in the Informative References section. to that document MAY appear in the Informative References section.
4.9. Validation Tools 4.10. Validation Tools
All modules need to be validated before submission in an Internet All modules need to be validated before submission in an Internet
Draft. The 'pyang' YANG compiler is freely available from github: Draft. The 'pyang' YANG compiler is freely available from github:
https://github.com/mbj4668/pyang https://github.com/mbj4668/pyang
If the 'pyang' compiler is used, then the "--ietf" command line If the 'pyang' compiler is used, then the "--ietf" command line
option SHOULD be used to identify any IETF guideline issues. option SHOULD be used to identify any IETF guideline issues.
4.10. Module Extraction Tools 4.11. Module Extraction Tools
A version of 'rfcstrip' is available which will extract YANG modules A version of 'rfcstrip' is available which will extract YANG modules
from an Internet Draft or RFC. The 'rfcstrip' tool which supports from an Internet Draft or RFC. The 'rfcstrip' tool which supports
YANG module extraction is freely available: YANG module extraction is freely available:
http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip
This tool can be used to verify that the "<CODE BEGINS>" and "<CODE This tool can be used to verify that the "<CODE BEGINS>" and "<CODE
ENDS>" tags are used correctly and that the normative YANG modules ENDS>" tags are used correctly and that the normative YANG modules
can be extracted correctly. can be extracted correctly.
5. YANG Usage Guidelines 5. YANG Usage Guidelines
In general, modules in IETF Standards Track specifications MUST In general, modules in IETF Standards Track specifications MUST
comply with all syntactic and semantic requirements of YANG comply with all syntactic and semantic requirements of YANG
[I-D.ietf-netmod-rfc6020bis]. The guidelines in this section are [RFC7950]. The guidelines in this section are intended to supplement
intended to supplement the YANG specification, which is intended to the YANG specification, which is intended to define a minimum set of
define a minimum set of conformance requirements. conformance requirements.
In order to promote interoperability and establish a set of practices In order to promote interoperability and establish a set of practices
based on previous experience, the following sections establish usage based on previous experience, the following sections establish usage
guidelines for specific YANG constructs. guidelines for specific YANG constructs.
Only guidelines that clarify or restrict the minimum conformance Only guidelines that clarify or restrict the minimum conformance
requirements are included here. requirements are included here.
5.1. Module Naming Conventions 5.1. Module Naming Conventions
Normative modules contained in Standards Track documents MUST be Normative modules contained in Standards Track documents MUST be
named according to the guidelines in the IANA Considerations section named according to the guidelines in the IANA Considerations section
of [I-D.ietf-netmod-rfc6020bis]. of [RFC7950].
A distinctive word or acronym (e.g., protocol name or working group A distinctive word or acronym (e.g., protocol name or working group
acronym) SHOULD be used in the module name. If new definitions are acronym) SHOULD be used in the module name. If new definitions are
being defined to extend one or more existing modules, then the same being defined to extend one or more existing modules, then the same
word or acronym should be reused, instead of creating a new one. word or acronym should be reused, instead of creating a new one.
All published module names MUST be unique. For a YANG module All published module names MUST be unique. For a YANG module
published in an RFC, this uniqueness is guaranteed by IANA. For published in an RFC, this uniqueness is guaranteed by IANA. For
unpublished modules, the authors need to check that no other work in unpublished modules, the authors need to check that no other work in
progress is using the same module name. progress is using the same module name.
skipping to change at page 16, line 17 skipping to change at page 16, line 17
All YANG definitions are scoped by the module containing the All YANG definitions are scoped by the module containing the
definition being referenced. This allows definitions from multiple definition being referenced. This allows definitions from multiple
modules to be used, even if the names are not unique. In the example modules to be used, even if the names are not unique. In the example
below, the identifier "foo" is used in all 3 modules: below, the identifier "foo" is used in all 3 modules:
module example-foo { module example-foo {
namespace "http://example.com/ns/foo"; namespace "http://example.com/ns/foo";
prefix f; prefix f;
container foo; container foo;
} }
module example-bar { module example-bar {
namespace "http://example.com/ns/bar"; namespace "http://example.com/ns/bar";
prefix b; prefix b;
typedef foo { type uint32; } typedef foo { type uint32; }
} }
module example-one { module example-one {
namespace "http://example.com/ns/one"; namespace "http://example.com/ns/one";
prefix one; prefix one;
import example-foo { prefix f; } import example-foo { prefix f; }
import example-bar { prefix b; } import example-bar { prefix b; }
augment "/f:foo" { augment "/f:foo" {
leaf foo { type b:foo; } leaf foo { type b:foo; }
} }
} }
YANG defines the following rules for prefix usage: YANG defines the following rules for prefix usage:
o Prefixes are never allowed for built in data types and YANG o Prefixes are never allowed for built in data types and YANG
keywords. keywords.
o A prefix MUST be used for any external statement (i.e., a o A prefix MUST be used for any external statement (i.e., a
statement defined with the YANG "extension" statement) statement defined with the YANG "extension" statement)
o The proper module prefix MUST be used for all identifiers imported o The proper module prefix MUST be used for all identifiers imported
skipping to change at page 17, line 25 skipping to change at page 17, line 25
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
between 1 and 64 characters in length. These include any construct between 1 and 64 characters in length. These include any construct
specified as an 'identifier-arg-str' token in the ABNF in Section 13 specified as an 'identifier-arg-str' token in the ABNF in Section 13
of [I-D.ietf-netmod-rfc6020bis]. of [RFC7950].
5.3.1. Identifier Naming Conventions 5.3.1. Identifier Naming Conventions
Identifiers SHOULD follow a consistent naming pattern throughout the Identifiers SHOULD follow a consistent naming pattern throughout the
module. Only lower-case letters, numbers, and dashes SHOULD be used module. Only lower-case letters, numbers, and dashes SHOULD be used
in identifier names. Upper-case characters and the underscore in identifier names. Upper-case characters and the underscore
character MAY be used if the identifier represents a well-known value character MAY be used if the identifier represents a well-known value
that uses these characters. that uses these characters.
Identifiers SHOULD include complete words and/or well-known acronyms Identifiers SHOULD include complete words and/or well-known acronyms
skipping to change at page 18, line 35 skipping to change at page 18, line 35
5.5. Conditional Statements 5.5. Conditional Statements
A module may be conceptually partitioned in several ways, using the A module may be conceptually partitioned in several ways, using the
'if-feature' and/or 'when' statements. 'if-feature' and/or 'when' statements.
Data model designers need to carefully consider all modularity Data model designers need to carefully consider all modularity
aspects, including the use of YANG conditional statements. aspects, including the use of YANG conditional statements.
If a data definition is optional, depending on server support for a If a data definition is optional, depending on server support for a
NETCONF protocol capability, then a YANG 'feature' statement SHOULD NETCONF or RESTCONF protocol capability, then a YANG 'feature'
be defined to indicate that the NETCONF capability is supported statement SHOULD be defined to indicate that the NETCONF or RESTCONF
within the data model. capability is supported within the data model.
If any notification data, or any data definition, for a non- If any notification data, or any data definition, for a non-
configuration data node is not mandatory, then the server may or may configuration data node is not mandatory, then the server may or may
not be required to return an instance of this data node. If any not be required to return an instance of this data node. If any
conditional requirements exist for returning the data node in a conditional requirements exist for returning the data node in a
notification payload or retrieval request, they MUST be documented notification payload or retrieval request, they MUST be documented
somewhere. For example, a 'when' or 'if-feature' statement could somewhere. For example, a 'when' or 'if-feature' statement could
apply to the data node, or the conditional requirements could be apply to the data node, or the conditional requirements could be
explained in a 'description' statement within the data node or one of explained in a 'description' statement within the data node or one of
its ancestors (if any). its ancestors (if any).
skipping to change at page 21, line 8 skipping to change at page 21, line 8
The 'local-name' function SHOULD NOT be used to reference local names The 'local-name' function SHOULD NOT be used to reference local names
outside of the YANG module defining the must or when expression outside of the YANG module defining the must or when expression
containing the 'local-name' function. Example of a local-name containing the 'local-name' function. Example of a local-name
function that should not be used: function that should not be used:
/*[local-name()='foo'] /*[local-name()='foo']
5.6.3. Axes 5.6.3. Axes
The 'attribute' and 'namespace' axes are not supported in YANG, and The 'attribute' and 'namespace' axes are not supported in YANG, and
MAY be empty in a NETCONF server implementation. MAY be empty in a NETCONF or RESTCONF server implementation.
The 'preceding', and 'following' axes SHOULD NOT be used. These The 'preceding', and 'following' axes SHOULD NOT be used. These
constructs rely on XML document order within a NETCONF server constructs rely on XML document order within a NETCONF or RESTCONF
configuration database, which may not be supported consistently or server configuration database, which may not be supported
produce reliable results across implementations. Predicate consistently or produce reliable results across implementations.
expressions based on static node properties (e.g., element name or Predicate expressions based on static node properties (e.g., element
value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The name or value, 'ancestor' or 'descendant' axes) SHOULD be used
'preceding' and 'following' axes MAY be used if document order is not instead. The 'preceding' and 'following' axes MAY be used if
relevant to the outcome of the expression (e.g., check for global document order is not relevant to the outcome of the expression
uniqueness of a parameter value). (e.g., check for global uniqueness of a parameter value).
The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used,
however they MAY be used if document order is not relevant to the however they MAY be used if document order is not relevant to the
outcome of the expression. outcome of the expression.
A server is only required to maintain the relative XML document order A server is only required to maintain the relative XML document order
of all instances of a particular user-ordered list or leaf-list. The of all instances of a particular user-ordered list or leaf-list. The
'preceding-sibling' and 'following-sibling' axes MAY be used if they 'preceding-sibling' and 'following-sibling' axes MAY be used if they
are evaluated in a context where the context node is a user-ordered are evaluated in a context where the context node is a user-ordered
'list' or 'leaf-list'. 'list' or 'leaf-list'.
skipping to change at page 23, line 27 skipping to change at page 23, line 27
type string; type string;
} }
leaf foo2 { leaf foo2 {
// CORRECT // CORRECT
must "/f:foo1 = 'one' or /f:foo1 = 'three'"; must "/f:foo1 = 'one' or /f:foo1 = 'three'";
type string; type string;
} }
In the next revision of the module, leaf "foo1" is extended with a In the next revision of the module, leaf "foo1" is extended with a
nem enum named "four": new enum named "four":
leaf foo1 { leaf foo1 {
type enumeration { type enumeration {
enum one; enum one;
enum two; enum two;
enum three; enum three;
enum four; enum four;
} }
} }
skipping to change at page 26, line 16 skipping to change at page 26, line 16
for Standards Track modules: for Standards Track modules:
urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock
urn:ietf:params:xml:ns:yang:ietf-netconf-state urn:ietf:params:xml:ns:yang:ietf-netconf-state
urn:ietf:params:xml:ns:yang:ietf-netconf urn:ietf:params:xml:ns:yang:ietf-netconf
Note that a different URN prefix string SHOULD be used for non- Note that a different URN prefix string SHOULD be used for non-
Standards-Track modules. The string SHOULD be selected according to Standards-Track modules. The string SHOULD be selected according to
the guidelines in [I-D.ietf-netmod-rfc6020bis]. the guidelines in [RFC7950].
The following examples are for non-Standards-Track modules. The The following examples are for non-Standards-Track modules. The
domain "example.com" SHOULD be used in all namespace URIs for example domain "example.com" SHOULD be used in all namespace URIs for example
modules. modules.
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
skipping to change at page 45, line 25 skipping to change at page 45, line 25
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 data. It can either be located within the configuration operational data. It can either be located within the configuration
subtree for which it applies, or it can be located outside the subtree for which it applies, or it can be located outside the
particular configuration subtree. Placing operational data within particular configuration subtree. Placing operational data within
the configuration subtree is appropriate if the operational values the configuration subtree is appropriate if the operational values
can only exist if the configuration exists. can only exist if the configuration exists. Placing operational data
outside the configuration subtree is appropriate if the operational
values can exist without corresponding configuration (e.g., system
generated interfaces).
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 data. 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 data 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. In this case it is RECOMMENDED to have a
separate config false value to represented the resulting state. For
instance:
leaf duplex-admin-mode { leaf duplex-admin-mode {
type enumeration { type enumeration {
enum auto; enum auto;
enum half; enum half;
enum full; enum full;
} }
} }
leaf duplex-oper-mode { leaf duplex-oper-mode {
skipping to change at page 49, line 44 skipping to change at page 49, line 44
list interface { list interface {
... ...
action reset { } action reset { }
} }
} }
5.27. 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 [RFC7950] MUST be followed for published
followed for published modules. They MAY be followed for unpublished 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 identify 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
to be unstable. For example, in the IETF, the RFC document is used to be unstable. For example, in the IETF, the RFC document is used
for published work, and the Internet-Draft is used for unpublished for published work, and the Internet-Draft is used for unpublished
work. work.
6. IANA Considerations 6. IANA Considerations
-- RFC Ed: These registries need to be updated to reference this
RFC instead of RFC 6087 for the ietf-template module, and
remove this note.
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 in [RFC6087] and updated by
this document.
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.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
Per this document, the following assignment has been made in the YANG The following assignment has been made in [RFC6087] and updated by
Module Names Registry for the YANG module template in Appendix C. this document in the YANG Module Names Registry, or the YANG module
template in Appendix C.
+-----------+-------------------------------------------+ +-----------+-------------------------------------------+
| Field | Value | | Field | Value |
+-----------+-------------------------------------------+ +-----------+-------------------------------------------+
| Name | ietf-template | | Name | ietf-template |
| Namespace | urn:ietf:params:xml:ns:yang:ietf-template | | Namespace | urn:ietf:params:xml:ns:yang:ietf-template |
| Prefix | temp | | Prefix | temp |
| Reference | RFC XXXX | | Reference | RFC XXXX |
+-----------+-------------------------------------------+ +-----------+-------------------------------------------+
YANG Registry Assignment YANG Registry Assignment
7. Security Considerations 7. Security Considerations
This document defines documentation guidelines for NETCONF content This document defines documentation guidelines for NETCONF or
defined with the YANG data modeling language. The guidelines for how RESTCONF content defined with the YANG data modeling language. The
to write a Security Considerations section for a YANG module are guidelines for how to write a Security Considerations section for a
defined in the online document YANG module are defined in the online document
http://trac.tools.ietf.org/area/ops/trac/wiki/ http://trac.tools.ietf.org/area/ops/trac/wiki/
yang-security-guidelines yang-security-guidelines
This document does not introduce any new or increased security risks This document does not introduce any new or increased security risks
into the management system. into the management system.
The following section contains the security considerations template The following section contains the security considerations template
dated 2010-06-16. Be sure to check the webpage at the URL listed dated 2010-06-16. Be sure to check the webpage at the URL listed
above in case there is a more recent version available. above in case there is a more recent version available.
skipping to change at page 55, line 51 skipping to change at page 55, 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 Clarified conventions for identifying code components
o Added YANG 1.1 guidelines o Added YANG 1.1 guidelines
o Added Data Model Constraints section o Added Data Model Constraints section
o Added mention of RESTCONF protocol
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-netmod-rfc6020bis]
Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)",
draft-ietf-netmod-rfc6020bis-07 (work in progress),
September 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors",
RFC 2223, October 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide
to the IETF Trust", BCP 78, RFC 5378, November 2008. to the IETF Trust", BCP 78, RFC 5378, November 2008.
[RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers,
and Boilerplates", RFC 5741, December 2009.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020, Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010. October 2010.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, June 2011.
[RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991,
July 2013. July 2013.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<http://www.rfc-editor.org/info/rfc7950>.
[W3C.REC-xpath-19991116] [W3C.REC-xpath-19991116]
Clark, J. and S. DeRose, "XML Path Language (XPath) Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999, Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
10.2. Informative References 10.2. Informative References
[I-D.ietf-netconf-restconf]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", draft-ietf-netconf-restconf-17 (work in
progress), September 2016.
[RFC-STYLE] [RFC-STYLE]
Braden, R., Ginoza, S., and A. Hagens, "RFC Document Braden, R., Ginoza, S., and A. Hagens, "RFC Document
Style", September 2009, Style", September 2009,
<http://www.rfc-editor.org/rfc-style-guide/rfc-style>. <http://www.rfc-editor.org/rfc-style-guide/rfc-style>.
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996,
<http://www.rfc-editor.org/info/rfc2026>. <http://www.rfc-editor.org/info/rfc2026>.
[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.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, June 2011.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<http://www.rfc-editor.org/info/rfc6242>.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
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.
[RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322,
DOI 10.17487/RFC7322, September 2014,
<http://www.rfc-editor.org/info/rfc7322>.
[RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed.,
"RFC Streams, Headers, and Boilerplates", RFC 7841,
DOI 10.17487/RFC7841, May 2016,
<http://www.rfc-editor.org/info/rfc7841>.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
A.1. v07 to v08 A.1. v08 to v09
o fixed references
o added mention of RESTCONF to abstract and intro
o created separate section for code components
o fixed document status
A.2. v07 to v08
o changed CODE BEGINS guideline for example modules o changed CODE BEGINS guideline for example modules
o updated tree diagram guidelines o updated tree diagram guidelines
o clarified published and unpublished terms o clarified published and unpublished terms
o added section on Empty and Boolean data types o added section on Empty and Boolean data types
o clarified how to update the revision statement o clarified how to update the revision statement
o updated operational state guidelines o updated operational state guidelines
o added 'YANG fragment' to terminology section o added 'YANG fragment' to terminology section
A.2. v06 to v07 A.3. 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.3. v05 to v06 A.4. 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 60, line 14 skipping to change at page 60, line 25
o Added section on using action vs. rpc o Added section on using action vs. rpc
o Changed term "operational state" to "operational data" o Changed term "operational state" to "operational data"
o Added section on YANG Data Node Constraints o Added section on YANG Data Node Constraints
o Added guidelines on using must vs. when statements o Added guidelines on using must vs. when statements
o Made ietf-foo module validate for I-D submission o Made ietf-foo module validate for I-D submission
A.4. v04 to v05 A.5. 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 60, line 36 skipping to change at page 60, line 47
o Added new section on guidelines for reusable groupings o Added new section on guidelines for reusable groupings
o Made header guidelines less IETF-specific o Made header guidelines less IETF-specific
o Added new section on guidelines for extension statements o Added new section on guidelines for extension statements
o Added guidelines for nested "choice" statement within a "case" o Added guidelines for nested "choice" statement within a "case"
statement statement
A.5. v03 ot v04 A.6. 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.6. v02 to v03 A.7. 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.7. v01 to v02 A.8. v01 to v02
o Updated draft based on mailing list comments. o Updated draft based on mailing list comments.
A.8. v00 to v01 A.9. 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 62, line 47 skipping to change at page 63, line 47
o IANA Considerations section -- this section must always be o IANA Considerations section -- this section must always be
present. For each module within the document, ensure that the present. For each module within the document, ensure that the
IANA Considerations section contains entries for the following IANA Considerations section contains entries for the following
IANA registries: IANA registries:
XML Namespace Registry: Register the YANG module namespace. XML Namespace Registry: Register the YANG module namespace.
YANG Module Registry: Register the YANG module name, prefix, YANG Module Registry: Register the YANG module name, prefix,
namespace, and RFC number, according to the rules specified namespace, and RFC number, according to the rules specified
in [I-D.ietf-netmod-rfc6020bis]. in [RFC7950].
o References -- verify that the references are properly divided o References -- verify that the references are properly divided
between normative and informative references, that RFC 2119 is between normative and informative references, that RFC 2119 is
included as a normative reference if the terminology defined included as a normative reference if the terminology defined
therein is used in the document, that all references required by therein is used in the document, that all references required by
the boilerplate are present, that all YANG modules containing the boilerplate are present, that all YANG modules containing
imported items are cited as normative references, and that all imported items are cited as normative references, and that all
citations point to the most current RFCs unless there is a valid citations point to the most current RFCs unless there is a valid
reason to do otherwise (for example, it is OK to include an reason to do otherwise (for example, it is OK to include an
informative reference to a previous version of a specification to informative reference to a previous version of a specification to
 End of changes. 70 change blocks. 
131 lines changed or deleted 172 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/