draft-ietf-netmod-rfc6087bis-01.txt   draft-ietf-netmod-rfc6087bis-02.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track October 23, 2014 Intended status: Standards Track April 24, 2015
Expires: April 26, 2015 Expires: October 26, 2015
Guidelines for Authors and Reviewers of YANG Data Model Documents Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-rfc6087bis-01 draft-ietf-netmod-rfc6087bis-02
Abstract Abstract
This memo provides guidelines for authors and reviewers of Standards This memo provides guidelines for authors and reviewers of Standards
Track specifications containing YANG data model modules. Applicable Track specifications containing YANG data model modules. Applicable
portions may be used as a basis for reviews of other YANG data model portions may be used as a basis for reviews of other YANG data model
documents. Recommendations and procedures are defined, which are documents. Recommendations and procedures are defined, which are
intended to increase interoperability and usability of Network intended to increase interoperability and usability of Network
Configuration Protocol (NETCONF) implementations that utilize YANG Configuration Protocol (NETCONF) implementations that utilize YANG
data model modules. data model modules.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 26, 2015. This Internet-Draft will expire on October 26, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 27 skipping to change at page 2, line 27
4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8
4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9
4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 9 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 9
4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 9 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 9
4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10
4.6. Security Considerations Section . . . . . . . . . . . . . 10 4.6. Security Considerations Section . . . . . . . . . . . . . 10
4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11
4.7.1. Documents that Create a New Namespace . . . . . . . . 11 4.7.1. Documents that Create a New Namespace . . . . . . . . 11
4.7.2. Documents that Extend an Existing Namespace . . . . . 11 4.7.2. Documents that Extend an Existing Namespace . . . . . 11
4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 11 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 11
4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12
5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 13 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 13
5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 13 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 13
5.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 13 5.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 13
5.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.4. Conditional Statements . . . . . . . . . . . . . . . . . . 14 5.4. Conditional Statements . . . . . . . . . . . . . . . . . . 14
5.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 14 5.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 15
5.5.1. Function Library . . . . . . . . . . . . . . . . . . . 14 5.5.1. Function Library . . . . . . . . . . . . . . . . . . . 15
5.5.2. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.5.2. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.5.3. Types . . . . . . . . . . . . . . . . . . . . . . . . 16 5.5.3. Types . . . . . . . . . . . . . . . . . . . . . . . . 16
5.5.4. Wildcards . . . . . . . . . . . . . . . . . . . . . . 16 5.5.4. Wildcards . . . . . . . . . . . . . . . . . . . . . . 17
5.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 17 5.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 17
5.7. Module Header, Meta, and Revision Statements . . . . . . . 17 5.7. Module Header, Meta, and Revision Statements . . . . . . . 18
5.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 18 5.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 19
5.9. Top-Level Data Definitions . . . . . . . . . . . . . . . . 19 5.9. Top-Level Data Definitions . . . . . . . . . . . . . . . . 20
5.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 20 5.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 20
5.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 21 5.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 21
5.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 21 5.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 21
5.13. Operation Definitions . . . . . . . . . . . . . . . . . . 22 5.13. Operation Definitions . . . . . . . . . . . . . . . . . . 23
5.14. Notification Definitions . . . . . . . . . . . . . . . . . 22 5.14. Notification Definitions . . . . . . . . . . . . . . . . . 23
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 5.15. Feature Definitions . . . . . . . . . . . . . . . . . . . 24
7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 5.16. Data Correlation . . . . . . . . . . . . . . . . . . . . . 24
7.1. Security Considerations Section Template . . . . . . . . . 25 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27
9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 28 7.1. Security Considerations Section Template . . . . . . . . . 27
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29
10.1. Normative References . . . . . . . . . . . . . . . . . . . 29 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 30
10.2. Informative References . . . . . . . . . . . . . . . . . . 29 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 31 10.1. Normative References . . . . . . . . . . . . . . . . . . . 31
A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 31 10.2. Informative References . . . . . . . . . . . . . . . . . . 31
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 32 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 33
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 34 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 33
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 36 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 34
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 36
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 38
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 [RFC6020] data models. YANG is used to define documents containing [RFC6020] data models. YANG is used to define
the data structures, protocol operations, and notification content the data structures, protocol operations, and notification content
skipping to change at page 5, line 5 skipping to change at page 4, line 44
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].
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
expected to know the YANG data modeling language before using this
document.
2. Terminology 2. Terminology
2.1. Requirements Notation 2.1. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
RFC 2119 language is used here to express the views of the NETMOD RFC 2119 language is used here to express the views of the NETMOD
working group regarding content for YANG modules. YANG modules working group regarding content for YANG modules. YANG modules
skipping to change at page 9, line 7 skipping to change at page 9, line 7
// ... // ...
revision 2010-01-18 { revision 2010-01-18 {
description "Latest revision"; description "Latest revision";
reference "RFC XXXX"; reference "RFC XXXX";
} }
// ... // ...
} }
<CODE ENDS> <CODE ENDS>
Note that this convention MUST NOT be used for example modules or
module fragments.
[FIXME: should a new convention called <EXAMPLE BEGINS> be added for
YANG example modules?]
4.2. Terminology Section 4.2. Terminology Section
A terminology section MUST be present if any terms are defined in the A terminology section MUST be present if any terms are defined in the
document or if any terms are imported from other documents. document or if any terms are imported from other documents.
If YANG tree diagrams are used, then a sub-section explaining the If YANG tree diagrams are used, then a sub-section explaining the
YANG tree diagram syntax MUST be present, containing the following YANG tree diagram syntax MUST be present, containing the following
text: text:
A simplified graphical representation of the data model is used in A simplified graphical representation of the data model is used in
skipping to change at page 10, line 30 skipping to change at page 10, 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 2010-06-16. Authors MUST check the considerations template dated 2013-05-08. Authors MUST check the
webpage at the URL listed above in case there is a more recent webpage at the URL listed above in case there is a more recent
version available. version 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
skipping to change at page 13, line 5 skipping to change at page 12, line 11
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
All modules need to be validated before submission in an Internet
Draft. The 'pyang' YANG compiler is freely available from github:
https://github.com/mbj4668/pyang
If the 'pyang' compiler is used, then the "--ietf" command line
option SHOULD be used to identify any IETF guideline issues.
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
[RFC6020]. The guidelines in this section are intended to supplement [RFC6020]. The guidelines in this section are intended to supplement
the YANG specification, which is intended to define a minimum set of the YANG specification, which is intended to 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
skipping to change at page 14, line 42 skipping to change at page 14, line 42
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).
If any 'if-feature' statements apply to a list node, then the same
'if-feature' statements MUST apply to any key leaf nodes for the
list. There MUST NOT be any 'if-feature' statements applied to any
key leaf that do not also apply to the parent list node.
There SHOULD NOT be any 'when' statements applied to a key leaf node.
It is possible that a 'when' statement for an ancestor node of a key
leaf will have the exact node-set result as the key leaf. In such as
case, the 'when' statement for the key leaf is redundant and SHOULD
be avoided.
5.5. XPath Usage 5.5. XPath Usage
This section describes guidelines for using the XML Path Language This section describes guidelines for using the XML Path Language
[W3C.REC-xpath-19991116] (XPath) within YANG modules. [W3C.REC-xpath-19991116] (XPath) within YANG modules.
5.5.1. Function Library 5.5.1. Function Library
The 'position' and 'last' functions SHOULD NOT be used. This applies The 'position' and 'last' functions SHOULD NOT be used. This applies
to implicit use of the 'position' function as well (e.g., to implicit use of the 'position' function as well (e.g.,
'//chapter[42]'). A server is only required to maintain the relative '//chapter[42]'). A server is only required to maintain the relative
skipping to change at page 15, line 27 skipping to change at page 15, line 39
to YANG because there is no 'lang' attribute set with the document. to YANG because there is no 'lang' attribute set with the document.
The YANG compiler SHOULD return 'false' for this function. The YANG compiler SHOULD return 'false' for this function.
The 'local-name', 'namespace-uri', 'name', 'string', and 'number' The 'local-name', 'namespace-uri', 'name', 'string', and 'number'
functions SHOULD NOT be used if the argument is a node-set. If so, functions SHOULD NOT be used if the argument is a node-set. If so,
the function result will be determined by the document order of the the function result will be determined by the document order of the
node-set. Since this order can be different on each server, the node-set. Since this order can be different on each server, the
function results can also be different. Any function call that function results can also be different. Any function call that
implicitly converts a node-set to a string will also have this issue. implicitly converts a node-set to a string will also have this issue.
The 'local-name' function SHOULD NOT be used to reference local names
outside of the YANG module defining the must or when expression
containing the 'local-name' function. Example of a local-name
function that should not be used:
/*[local-name()='foo']
5.5.2. Axes 5.5.2. 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 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 server
configuration database, which may not be supported consistently or configuration database, which may not be supported consistently or
produce reliable results across implementations. Predicate produce reliable results across implementations. Predicate
expressions based on static node properties (e.g., element name or expressions based on static node properties (e.g., element name or
value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The
'preceding' and 'following' axes MAY be used if document order is not 'preceding' and 'following' axes MAY be used if document order is not
relevant to the outcome of the expression (e.g., check for global relevant to the outcome of the expression (e.g., check for global
uniqueness of a parameter value). 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
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'.
5.5.3. Types 5.5.3. Types
Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT
skipping to change at page 19, line 18 skipping to change at page 19, line 36
A standard namespace statement value SHOULD have the following form: A standard namespace statement value SHOULD have the following form:
<URN prefix string>:<module-name> <URN prefix string>:<module-name>
The following URN prefix string SHOULD be used for published and The following URN prefix string SHOULD be used for published and
unpublished YANG modules: unpublished YANG modules:
urn:ietf:params:xml:ns:yang: urn:ietf:params:xml:ns:yang:
The following example URNs would be valid temporary namespace The following example URNs would be valid namespace statement values
statement values 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 [RFC6020]. the guidelines in [RFC6020].
skipping to change at page 19, line 47 skipping to change at page 20, line 17
http://example.com/ns/example-system http://example.com/ns/example-system
5.9. Top-Level Data Definitions 5.9. Top-Level Data Definitions
The top-level data organization SHOULD be considered carefully, in The top-level data organization SHOULD be considered carefully, in
advance. Data model designers need to consider how the functionality advance. Data model designers need to consider how the functionality
for a given protocol or protocol family will grow over time. for a given protocol or protocol family will grow over time.
The separation of configuration data and operational state SHOULD be The separation of configuration data and operational state SHOULD be
considered carefully. It is often useful to define separate top- considered carefully. It is often useful to define separate top-
level containers for configuration and non-configuration data. There level containers for configuration and non-configuration data.
SHOULD only be one top-level data node defined in each YANG module
for all configuration data nodes, if any configuration data nodes are The number of top-level data nodes within a module SHOULD be
defined at all. There MAY be one top-level data node defined in each minimized. It is often useful to retrieve related information within
YANG module for all non-configuration data nodes, if any non- a single subtree. If data is too distributed, is becomes difficult
configuration data nodes are defined at all. 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.
A mandatory database data definition is defined as a node that a A mandatory database data definition is defined as a node that a
client must provide for the database to be valid. The server is not client must provide for the database to be valid. The server is not
required to provide a value. required to provide a value.
Top-level database data definitions MUST NOT be mandatory. If a Top-level database data definitions MUST NOT be mandatory. If a
skipping to change at page 22, line 22 skipping to change at page 22, line 43
If the data definition semantics are defined in an external document, If the data definition semantics are defined in an external document,
(other than another YANG module indicated by an import statement), (other than another YANG module indicated by an import statement),
then a reference statement MUST be present. then a reference statement MUST be present.
The 'anyxml' construct may be useful to represent an HTML banner The 'anyxml' construct may be useful to represent an HTML banner
containing markup elements, such as '&lt;b&gt;' and '&lt;/b&gt;', and containing markup elements, such as '&lt;b&gt;' and '&lt;/b&gt;', and
MAY be used in such cases. However, this construct SHOULD NOT be MAY be used in such cases. However, this construct SHOULD NOT be
used if other YANG data node types can be used instead to represent used if other YANG data node types can be used instead to represent
the desired syntax and semantics. the desired syntax and semantics.
It has been found that the 'anyxml' statement is not implemented
consistently across all servers. It is possible that mixed mode XML
will not be supported, or configuration anyxml nodes will not
supported.
If there are referential integrity constraints associated with the If there are referential integrity constraints associated with the
desired semantics that can be represented with XPath, then one or desired semantics that can be represented with XPath, then one or
more 'must' statements SHOULD be present. more 'must' statements SHOULD be present.
For list and leaf-list data definitions, if the number of possible For list and leaf-list data definitions, if the number of possible
instances is required to be bounded for all implementations, then the instances is required to be bounded for all implementations, then the
max-elements statements SHOULD be present. max-elements statements SHOULD be present.
If any 'must' or 'when' statements are used within the data If any 'must' or 'when' statements are used within the data
definition, then the data definition description statement SHOULD definition, then the data definition description statement SHOULD
skipping to change at page 24, line 5 skipping to change at page 23, line 46
notification interface-up { notification interface-up {
description "Sent when an interface is activated."; description "Sent when an interface is activated.";
leaf name { leaf name {
type leafref { type leafref {
path "/if:interfaces/if:interface/if:name"; path "/if:interfaces/if:interface/if:name";
} }
} }
} }
Note that there are no formal YANG statements to identify any data
node resources associated with a notification. The description
statement for the notification SHOULD specify if and how the
notification identifies any data node resources associated with the
specific event.
5.15. Feature Definitions
The YANG "feature" statement is used to define a label for a set of
optional functionality within a module. The "if-feature" statement
is used in the YANG statements associated with a feature.
The set of YANG features available in a module should be considered
carefully. The description-stmt within a feature-stmt MUST specify
any interactions with other features.
If there is a large set of objects associated with a YANG feature,
then consider moving those objects to a separate module, instead of
using a YANG feature. Note that the set of features within a module
is easily discovered by the reader, but the set of related modules
within the entire YANG library is not as easy to identity. Module
names with a common prefix can help readers identity the set of
related modules, but this assumes the reader will have discovered and
installed all the relevant modules.
If one feature requires implementation of another feature, then an
"if-feature" statement SHOULD be used in the dependent "feature"
statement.
For example, feature2 requires implementation of feature1:
feature feature1 {
description "Some protocol feature";
}
feature feature2 {
if-feature "feature1";
description "Another protocol feature";
}
5.16. Data Correlation
Data can be correlated in various ways, using common data types,
common data naming, and common data organization. There are several
ways to extend the functionality of a module, based on the degree of
coupling between the old and new functionality:
o inline: update the module with new protocol-accessible objects.
The naming and data organization of the original objects is used.
The new objects are in the original module namespace.
o augment: create a new module with new protocol-accessible objects
that augment the original data structure. The naming and data
organization of the original objects is used. The new objects are
in the new module namespace.
o mirror: create new objects in a new module or the original module,
except use new a naming scheme and data location. The naming can
be coupled in different ways. Tight coupling is achieved with a
"leafref" data type. This method SHOULD be used. If the new data
instances are not limited to the values in use in the original
data structure, then the "require-instance" sub-statement MUST be
set to "false". Loose coupling is achieved by using key leafs
with the same data type as the original data structure.
It is sometimes useful to separate configuration and operational
state, so that they do not not even share the exact same naming
characteristics. The correlation between configuration the
operational state data that is affected by changes in configuration
is a complex problem. There may not be a simple 1:1 relationship
between a configuration data node and an operational data node.
Further work is needed in YANG to clarify this relationship.
Protocol work may also be needed to allow a client to retrieve this
type of information from a server. At this time the best practice is
to clearly document any relationship to other data structures in the
"description" statement.
6. IANA Considerations 6. IANA Considerations
This document registers one URI in the IETF XML registry [RFC3688]. This document registers one URI in the IETF XML registry [RFC3688].
The following registration has been made: The following registration has been made:
URI: urn:ietf:params:xml:ns:yang:ietf-template URI: urn:ietf:params:xml:ns:yang:ietf-template
Registrant Contact: The NETMOD WG of the IETF. Registrant Contact: The NETMOD WG of the IETF.
skipping to change at page 28, line 25 skipping to change at page 30, line 25
o Updated obsolete URLs for IETF resources o Updated obsolete URLs for IETF resources
o Changed top-level data node guideline o Changed top-level data node guideline
o Clarified XPath usage for a literal value representing a YANG o Clarified XPath usage for a literal value representing a YANG
identity identity
o Clarified XPath usage for a when-stmt o Clarified XPath usage for a when-stmt
o Clarified XPath usage for 'proceeding-sibling' and
'following-sibling' axes
o Added terminology guidelines o Added terminology guidelines
o Added YANG tree diagram definition and guideline o Added YANG tree diagram definition and guideline
o Updated XPath guidelines for type conversions and function library o Updated XPath guidelines for type conversions and function library
usage. usage.
o Updated data types section o Updated data types section
o Updated notifications section o Updated notifications section
o Clarified conditional key leaf nodes
o Clarify usage of 'uint64' and 'int64' data types
o Added text on YANG feature usage
10. References 10. References
10.1. Normative References 10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors",
RFC 2223, October 1997. RFC 2223, October 1997.
skipping to change at page 31, line 21 skipping to change at page 33, line 21
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
o Issue 2: XPath function restrictions: Added paragraphs in XPath o Issue 2: XPath function restrictions: Added paragraphs in XPath
usage section for 'id', 'namesapce-uri', 'name', and 'lang' usage section for 'id', 'namespace-uri', 'name', and 'lang'
functions functions
o Issue 3: XPath function document order issues: Added paragraph in o Issue 3: XPath function document order issues: Added paragraph in
XPath usage section about node-set ordering for 'local-name', XPath usage section about node-set ordering for 'local-name',
'namespace-uri', 'name', 'string' and 'number' functions. Also 'namespace-uri', 'name', 'string' and 'number' functions. Also
any function that implicitly converts a node-set to a string. any function that implicitly converts a node-set to a string.
o Issue 4: XPath preceding-sibling and following-sibling: Checked o Issue 4: XPath preceding-sibling and following-sibling: Checked
and text in XPath usage section already has proposed text from and text in XPath usage section already has proposed text from
Lada. Lada.
 End of changes. 23 change blocks. 
37 lines changed or deleted 171 lines changed or added

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