draft-ietf-netmod-rfc6087bis-02.txt   draft-ietf-netmod-rfc6087bis-03.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track April 24, 2015 Intended status: Standards Track June 12, 2015
Expires: October 26, 2015 Expires: December 14, 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-02 draft-ietf-netmod-rfc6087bis-03
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 October 26, 2015. This Internet-Draft will expire on December 14, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2015 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
skipping to change at page 2, line 28 skipping to change at page 2, line 28
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 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12
4.10. Module Extraction 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. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 15
5.4. Conditional Statements . . . . . . . . . . . . . . . . . . 14 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 15
5.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 15 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.5.1. Function Library . . . . . . . . . . . . . . . . . . . 15 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 16
5.5.2. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 17
5.5.3. Types . . . . . . . . . . . . . . . . . . . . . . . . 16 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 17
5.5.4. Wildcards . . . . . . . . . . . . . . . . . . . . . . 17 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 18
5.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 17 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.7. Module Header, Meta, and Revision Statements . . . . . . . 18 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 19
5.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 19 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 20
5.9. Top-Level Data Definitions . . . . . . . . . . . . . . . . 20 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 20
5.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 20 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 21
5.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 21 5.8. Module Header, Meta, and Revision Statements . . . . . . . 22
5.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 21 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 23
5.13. Operation Definitions . . . . . . . . . . . . . . . . . . 23 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 24
5.14. Notification Definitions . . . . . . . . . . . . . . . . . 23 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 24
5.15. Feature Definitions . . . . . . . . . . . . . . . . . . . 24 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 25
5.16. Data Correlation . . . . . . . . . . . . . . . . . . . . . 24 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 25
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 26
7. Security Considerations . . . . . . . . . . . . . . . . . . . 27
7.1. Security Considerations Section Template . . . . . . . . . 27 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 27
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 5.13. Data Definitions . . . . . . . . . . . . . . . . . . . . . 28
9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 30 5.14. Operation Definitions . . . . . . . . . . . . . . . . . . 29
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.15. Notification Definitions . . . . . . . . . . . . . . . . . 29
10.1. Normative References . . . . . . . . . . . . . . . . . . . 31 5.16. Feature Definitions . . . . . . . . . . . . . . . . . . . 30
10.2. Informative References . . . . . . . . . . . . . . . . . . 31 5.17. Augment Statements . . . . . . . . . . . . . . . . . . . . 31
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 33 5.17.1. Conditional Augment Statements . . . . . . . . . . . . 31
A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 33 5.17.2. Conditionally Mandatory Data Definition Statements . . 31
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 34 5.18. Data Correlation . . . . . . . . . . . . . . . . . . . . . 33
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 36 5.19. Operational State . . . . . . . . . . . . . . . . . . . . 33
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 38 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37
7. Security Considerations . . . . . . . . . . . . . . . . . . . 38
7.1. Security Considerations Section Template . . . . . . . . . 38
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40
9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 41
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42
10.1. Normative References . . . . . . . . . . . . . . . . . . . 42
10.2. Informative References . . . . . . . . . . . . . . . . . . 42
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 44
A.1. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . . 44
A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . . 44
A.3. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 44
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 46
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 48
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 50
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 8, line 36 skipping to change at page 8, line 36
4.1. Module Copyright 4.1. Module Copyright
The module description statement MUST contain a reference to the The module description statement MUST contain a reference to the
latest approved IETF Trust Copyright statement, which is available latest approved IETF Trust Copyright statement, which is available
online at: online at:
http://trustee.ietf.org/license-info/ http://trustee.ietf.org/license-info/
Each YANG module or submodule contained within an Internet-Draft or Each YANG module or submodule contained within an Internet-Draft or
RFC is considered to be a code component. The strings '<CODE RFC is considered to be a code component. The strings "<CODE
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 [RFC6020]. The following the file name specified in Section 5.2 of [RFC6020]. The following
example is for the '2010-01-18' revision of the 'ietf-foo' module: example is for the '2010-01-18' revision of the 'ietf-foo' module:
<CODE BEGINS> file "ietf-foo@2010-01-18.yang" <CODE BEGINS> file "ietf-foo@2010-01-18.yang"
module ietf-foo { module ietf-foo {
// ... // ...
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 Note that this convention MUST NOT be used for example modules or
module fragments. 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 13, line 5 skipping to change at page 12, line 16
4.9. Validation Tools 4.9. 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
A version of 'rfcstrip' is available which will extract YANG modules
from an Internet Draft or RFC. The 'rfcstrip' tool which supports
YANG module extraction is freely available:
http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip
This tool can be used to verify that the "<CODE BEGINS>" and "<CODE
ENDS>" tags are used correctly and that the normative YANG modules
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
[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 13, line 39 skipping to change at page 13, line 39
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.
Once a module name is published, it MUST NOT be reused, even if the Once a module name is published, it MUST NOT be reused, even if the
RFC containing the module is reclassified to 'Historic' status. RFC containing the module is reclassified to 'Historic' status.
5.2. Identifiers 5.2. Prefixes
All YANG definitions are scoped by the module containing the
definition being referenced. This allows definitions from multiple
modules to be used, even if the names are not unique. In the example
below, the identifier "foo" is used in all 3 modules:
module example-foo {
namespace "http://example.com/ns/foo";
prefix f;
container foo;
}
module example-bar {
namespace "http://example.com/ns/bar";
prefix b;
typedef foo { type uint32; }
}
module example-one {
namespace "http://example.com/ns/one";
prefix one;
import example-foo { prefix f; }
import example-bar { prefix b; }
augment "/f:foo" {
leaf foo { type b:foo; }
}
}
YANG defines the following rules for prefix usage:
o Prefixes are never allowed for built in data types and YANG
keywords.
o A prefix MUST be used for any external statement (i.e., a
statement defined with the YANG "extension" statement)
o The proper module prefix MUST be used for all identifiers imported
from other modules
o The proper module prefix MUST be used for all identifiers included
from a submodule.
The following guidelines apply to prefix usage of the current (local)
module:
o The local module prefix SHOULD be used instead of no prefix in all
path expressions.
o The local module prefix MUST be used instead of no prefix in all
"default" statements for an "identityref" or "instance-identifier"
data type
o The lcaol module prefix MAY be used for references to typedefs,
groupings, extensions, features, and identities defined in the
module.
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 12 specified as an 'identifier-arg-str' token in the ABNF in Section 12
of [RFC6020]. of [RFC6020].
5.3. Defaults 5.3.1. Identifier Naming Conventions
Identifiers SHOULD follow a consistent naming pattern throughout the
module. Only lower-case letters, numbers, and dashes SHOULD be used
in identifier names. Upper-case characters and the underscore
character MAY be used if the identifier represents a well-known value
that uses these characters.
Identifiers SHOULD include complete words and/or well-known acronyms
or abbreviations. Child nodes within a container or list SHOULD NOT
replicate the parent identifier. YANG identifiers are hierarchical
and are only meant to be unique within the the set of sibling nodes
defined in the same module namespace.
It is permissible to use common identifiers such as "name" or "id" in
data definition statements, especially if these data nodes share a
common data type.
Identifiers SHOULD NOT carry any special semantics that identify data
modelling properties. Only YANG statements and YANG extension
statements are designed to convey machine readable data modelling
properties. For example, naming an object "config" or "state" does
not change whether it is configuration data or state data. Only
defined YANG statements or YANG extension statements can be used to
assign semantics in a machine readable format in YANG.
5.4. Defaults
In general, it is suggested that substatements containing very common In general, it is suggested that substatements containing very common
default values SHOULD NOT be present. The following substatements default values SHOULD NOT be present. The following substatements
are commonly used with the default value, which would make the module are commonly used with the default value, which would make the module
difficult to read if used everywhere they are allowed. difficult to read if used everywhere they are allowed.
+--------------+---------------+ +--------------+---------------+
| Statement | Default Value | | Statement | Default Value |
+--------------+---------------+ +--------------+---------------+
| config | true | | config | true |
| mandatory | false | | mandatory | false |
| max-elements | unbounded | | max-elements | unbounded |
| min-elements | 0 | | min-elements | 0 |
| ordered-by | system | | ordered-by | system |
| status | current | | status | current |
| yin-element | false | | yin-element | false |
+--------------+---------------+ +--------------+---------------+
Statement Defaults Statement Defaults
5.4. 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 protocol capability, then a YANG 'feature' statement SHOULD
be defined to indicate that the NETCONF capability is supported be defined to indicate that the NETCONF capability is supported
skipping to change at page 14, line 49 skipping to change at page 16, line 49
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 any 'if-feature' statements apply to a list node, then the same
'if-feature' statements MUST apply to any key leaf nodes for the 'if-feature' statements MUST apply to any key leaf nodes for the
list. There MUST NOT be any 'if-feature' statements applied to any list. There MUST NOT be any 'if-feature' statements applied to any
key leaf that do not also apply to the parent list node. 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. 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 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 leaf will have the exact node-set result as the key leaf. In such a
case, the 'when' statement for the key leaf is redundant and SHOULD case, the 'when' statement for the key leaf is redundant and SHOULD
be avoided. be avoided.
5.5. XPath Usage 5.6. 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.6.1. XPath Evaluation Contexts
YANG defines 5 separate contexts for evaluation of XPath statements:
1) The "running" datastore: collection of all YANG configuration data
nodes. The document root is the conceptual container, (e.g.,
"config" in the "edit-config" operation), which is the parent of all
top-level data definition statements with a "config" statement value
of "true".
2) State data + the "running" datastore: collection of all YANG data
nodes. The document root is the conceptual container, parent of all
top-level data definition statements.
3) Notification: an event notification document. The document root
is the notification element.
4) RPC Input: The document root is the conceptual "input" node, which
is the parent of all RPC input parameter definitions.
5) RPC Output: The document root is the conceptual "output" node,
which is the parent of all RPC output parameter definitions.
Note that these XPath contexts cannot be mixed. For example, a
"when" statement in a notification context cannot reference
configuration data.
notification foo {
leaf mtu {
// NOT OK because when-stmt context is this notification
when "/if:interfaces/if:interface[name='eth0']";
type leafref {
// OK because path-stmt has a different context
path "/if:interfaces/if:interface/if:mtu";
}
}
}
It is especially important to consider the XPath evaluation context
for XPath expressions defined in groupings. An XPath expression
defined in a grouping may not be portable, meaning it cannot be used
in multiple contexts and produce proper results.
If the XPath expressions defined in a grouping are intended for a
particular context, then this context SHOULD be identified in the
"description" statement for the grouping.
5.6.2. 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
XML document order of all instances of a particular user-ordered list XML document order of all instances of a particular user-ordered list
or leaf-list. The 'position' and 'last' functions MAY be used if or leaf-list. The 'position' and 'last' functions MAY be used if
they are evaluated in a context where the context node is a user- they are evaluated in a context where the context node is a user-
ordered 'list' or 'leaf-list'. ordered 'list' or 'leaf-list'.
The 'id' function SHOULD NOT be used. The 'ID' attribute is not The 'id' function SHOULD NOT be used. The 'ID' attribute is not
skipping to change at page 15, line 46 skipping to change at page 18, line 45
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 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.5.2. 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 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
skipping to change at page 16, line 22 skipping to change at page 19, line 21
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'.
5.5.3. Types 5.6.4. 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
be used within numeric or boolean expressions. There are boundary be used within numeric or boolean expressions. There are boundary
conditions in which the translation from the YANG 64-bit type to an conditions in which the translation from the YANG 64-bit type to an
XPath number can cause incorrect results. Specifically, an XPath XPath number can cause incorrect results. Specifically, an XPath
'double' precision floating point number cannot represent very large 'double' precision floating point number cannot represent very large
positive or negative 64-bit numbers because it only provides a total positive or negative 64-bit numbers because it only provides a total
precision of 53 bits. The 'int64' and 'uint64' data types MAY be precision of 53 bits. The 'int64' and 'uint64' data types MAY be
used in numeric expressions if the value can be represented with no used in numeric expressions if the value can be represented with no
more than 53 bits of precision. more than 53 bits of precision.
skipping to change at page 17, line 16 skipping to change at page 20, line 16
augment "/rt:active-route/rt:input/rt:destination-address" { augment "/rt:active-route/rt:input/rt:destination-address" {
when "rt:address-family='v4ur:ipv4-unicast'" { when "rt:address-family='v4ur:ipv4-unicast'" {
description description
"This augment is valid only for IPv4 unicast."; "This augment is valid only for IPv4 unicast.";
} }
// nodes defined here within the augment-stmt // nodes defined here within the augment-stmt
// cannot be referenced in the when-stmt // cannot be referenced in the when-stmt
} }
5.5.4. Wildcards 5.6.5. Wildcards
It is possible to construct XPath expressions that will evaluate It is possible to construct XPath expressions that will evaluate
differently when combined with several modules within a server differently when combined with several modules within a server
implementation, then when evaluated within the single module. This implementation, then when evaluated within the single module. This
is due to augmenting nodes from other modules. is due to augmenting nodes from other modules.
Wildcard expansion is done within a server against all the nodes from Wildcard expansion is done within a server against all the nodes from
all namespaces, so it is possible for a 'must' or 'when' expression all namespaces, so it is possible for a 'must' or 'when' expression
that uses the '*' operator will always evaluate to false if processed that uses the '*' operator will always evaluate to false if processed
within a single YANG module. In such cases, the 'description' within a single YANG module. In such cases, the 'description'
statement SHOULD clarify that augmenting objects are expected to statement SHOULD clarify that augmenting objects are expected to
match the wildcard expansion. match the wildcard expansion.
when /foo/services/*/active { when /foo/services/*/active {
description description
"No services directly defined in this module. "No services directly defined in this module.
Matches objects that have augmented the services container."; Matches objects that have augmented the services container.";
} }
5.6. Lifecycle Management 5.6.6. Boolean Expressions
The YANG "must" and "when" statements use an XPath boolean expression
to define the test condition for the statement. It is important to
specify these expressions in a way that will not cause inadvertent
changes in the result if the objects referenced in the expression are
updated in future revisions of the module.
For example, the leaf "foo2" must exist if the leaf "foo1" is equal
to "one" or "three":
leaf foo1 {
type enumeration {
enum one;
enum two;
enum three;
}
}
leaf foo2 {
// INCORRECT
must "/f:foo1 != 'two'";
type string;
}
leaf foo2 {
// CORRECT
must "/f:foo1 = 'one' or /f:foo1 = 'three'";
type string;
}
In the next revision of the module, leaf "foo1" is extended with a
nem enum named "four":
leaf foo1 {
type enumeration {
enum one;
enum two;
enum three;
enum four;
}
}
Now the first XPath expression will allow the enum "four" to be
accepted in addition to the "one" and "three" enum values.
5.7. Lifecycle Management
The status statement MUST be present if its value is 'deprecated' or The status statement MUST be present if its value is 'deprecated' or
'obsolete'. The status SHOULD NOT be changed from 'current' directly 'obsolete'. The status SHOULD NOT be changed from 'current' directly
to 'obsolete'. An object SHOULD be available for at least one year to 'obsolete'. An object SHOULD be available for at least one year
with 'deprecated' status before it is changed to 'obsolete'. with 'deprecated' status before it is changed to 'obsolete'.
The module or submodule name MUST NOT be changed, once the document The module or submodule name MUST NOT be changed, once the document
containing the module or submodule is published. containing the module or submodule is published.
The module namespace URI value MUST NOT be changed, once the document The module namespace URI value MUST NOT be changed, once the document
skipping to change at page 18, line 11 skipping to change at page 22, line 16
present if any groupings are used from the external module. present if any groupings are used from the external module.
The revision-date substatement within the include statement SHOULD be The revision-date substatement within the include statement SHOULD be
present if any groupings are used from the external submodule. present if any groupings are used from the external submodule.
If submodules are used, then the document containing the main module If submodules are used, then the document containing the main module
MUST be updated so that the main module revision date is equal or MUST be updated so that the main module revision date is equal or
more recent than the revision date of any submodule that is (directly more recent than the revision date of any submodule that is (directly
or indirectly) included by the main module. or indirectly) included by the main module.
5.7. Module Header, Meta, and Revision Statements 5.8. Module Header, Meta, and Revision Statements
For published modules, the namespace MUST be a globally unique URI, For published modules, the namespace MUST be a globally unique URI,
as defined in [RFC3986]. This value is usually assigned by the IANA. as defined in [RFC3986]. This value is usually assigned by the IANA.
The organization statement MUST be present. If the module is The organization statement MUST be present. If the module is
contained in a document intended for Standards Track status, then the contained in a document intended for Standards Track status, then the
organization SHOULD be the IETF working group chartered to write the organization SHOULD be the IETF working group chartered to write the
document. document.
The contact statement MUST be present. If the module is contained in The contact statement MUST be present. If the module is contained in
skipping to change at page 19, line 7 skipping to change at page 23, line 11
Each new revision MUST include a revision date that is higher than Each new revision MUST include a revision date that is higher than
any other revision date in the module. The revision date does not any other revision date in the module. The revision date does not
need to be updated if the module contents do not change in the new need to be updated if the module contents do not change in the new
document revision. document revision.
It is acceptable to reuse the same revision statement within It is acceptable to reuse the same revision statement within
unpublished versions (i.e., Internet-Drafts), but the revision date unpublished versions (i.e., Internet-Drafts), but the revision date
MUST be updated to a higher value each time the Internet-Draft is re- MUST be updated to a higher value each time the Internet-Draft is re-
posted. posted.
5.8. Namespace Assignments 5.9. Namespace Assignments
It is RECOMMENDED that only valid YANG modules be included in It is RECOMMENDED that only valid YANG modules be included in
documents, whether or not they are published yet. This allows: documents, whether or not they are published yet. This allows:
o the module to compile correctly instead of generating disruptive o the module to compile correctly instead of generating disruptive
fatal errors. fatal errors.
o early implementors to use the modules without picking a random o early implementors to use the modules without picking a random
value for the XML namespace. value for the XML namespace.
skipping to change at page 19, line 49 skipping to change at page 24, line 5
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].
The following examples of non-Standards-Track modules are only The following examples are for non-Standards-Track modules. The
suggestions. There are no guidelines for this type of URN in this domain "example.com" SHOULD be used in all namespace URIs for example
document: 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.9. Top-Level Data Definitions 5.10. Top-Level Data Definitions
The top-level data organization SHOULD be considered carefully, in The top-level data organization SHOULD be considered carefully, in
advance. Data model designers need to consider how the functionality advance. Data model designers need to consider how the functionality
for a given protocol or protocol family will grow over time. for a given protocol or protocol family will grow over time.
The separation of configuration data and operational state SHOULD be The separation of configuration data and operational 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. level containers for configuration and non-configuration data.
The number of top-level data nodes within a module SHOULD be The number of top-level data nodes within a module SHOULD be
skipping to change at page 20, line 37 skipping to change at page 24, line 41
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
mandatory node appears at the top level, it will immediately cause mandatory node appears at the top level, it will immediately cause
the database to be invalid. This can occur when the server boots or the database to be invalid. This can occur when the server boots or
when a module is loaded dynamically at runtime. when a module is loaded dynamically at runtime.
5.10. Data Types 5.11. Data Types
Selection of an appropriate data type (i.e., built-in type, existing Selection of an appropriate data type (i.e., built-in type, existing
derived type, or new derived type) is very subjective, and therefore derived type, or new derived type) is very subjective, and therefore
few requirements can be specified on that subject. few requirements can be specified on that subject.
Data model designers SHOULD use the most appropriate built-in data Data model designers SHOULD use the most appropriate built-in data
type for the particular application. type for the particular application.
The signed numeric data types (i.e., 'int8', 'int16', 'int32', and
'int64') SHOULD NOT be used unless negative values are allowed for
the desired semantics.
5.11.1. Fixed Value Extensibility
If the set of values is fixed and the data type contents are
controlled by a single naming authority, then an enumeration data
type SHOULD be used.
leaf foo {
type enumeration {
enum one;
enum two;
}
}
If extensibility of enumerated values is required, then the If extensibility of enumerated values is required, then the
'identityref' data type SHOULD be used instead of an enumeration or 'identityref' data type SHOULD be used instead of an enumeration or
other built-in type. other built-in type.
identity foo-type {
description "Base for the extensible type";
}
identity one {
base f:foo-type;
}
identity two {
base f:foo-type;
}
leaf foo {
type identityref {
base f:foo-type;
}
}
Note that any module can declare an identity with base "foo-type"
that is valid for the "foo" leaf. Identityref values are considered
to be qualified names.
5.11.2. Patterns and Ranges
For string data types, if a machine-readable pattern can be defined For string data types, if a machine-readable pattern can be defined
for the desired semantics, then one or more pattern statements SHOULD for the desired semantics, then one or more pattern statements SHOULD
be present. A single quoted string SHOULD be used to specify the be present. A single quoted string SHOULD be used to specify the
pattern, since a double-quoted string can modify the content. pattern, since a double-quoted string can modify the content.
The following typedef from [RFC6991] demonstrates the proper use of
the "pattern" statement:
typedef ipv4-address-no-zone {
type inet:ipv4-address {
pattern '[0-9\.]*';
}
...
}
For string data types, if the length of the string is required to be For string data types, if the length of the string is required to be
bounded in all implementations, then a length statement MUST be bounded in all implementations, then a length statement MUST be
present. present.
The following typedef from [RFC6991] demonstrates the proper use of
the "length" statement:
typedef yang-identifier {
type string {
length "1..max";
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*';
pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*';
}
...
}
For numeric data types, if the values allowed by the intended For numeric data types, if the values allowed by the intended
semantics are different than those allowed by the unbounded intrinsic semantics are different than those allowed by the unbounded intrinsic
data type (e.g., 'int32'), then a range statement SHOULD be present. data type (e.g., 'int32'), then a range statement SHOULD be present.
The signed numeric data types (i.e., 'int8', 'int16', 'int32', and The following typedef from [RFC6991] demonstrates the proper use of
'int64') SHOULD NOT be used unless negative values are allowed for the "range" statement:
the desired semantics.
typedef dscp {
type uint8 {
range "0..63";
}
...
}
5.11.3. Enumerations and Bits
For 'enumeration' or 'bits' data types, the semantics for each 'enum' For 'enumeration' or 'bits' data types, the semantics for each 'enum'
or 'bit' SHOULD be documented. A separate description statement or 'bit' SHOULD be documented. A separate description statement
(within each 'enum' or 'bit' statement) SHOULD be present. (within each 'enum' or 'bit' statement) SHOULD be present.
5.11. Reusable Type Definitions leaf foo {
// INCORRECT
type enumeration {
enum one;
enum two;
}
description
"The foo enum...
one: The first enum
two: The second enum";
}
leaf foo {
// CORRECT
type enumeration {
enum one {
description "The first enum";
}
enum two {
description "The second enum";
}
}
description
"The foo enum... ";
}
5.12. Reusable Type Definitions
If an appropriate derived type exists in any standard module, such as If an appropriate derived type exists in any standard module, such as
[RFC6991], then it SHOULD be used instead of defining a new derived [RFC6991], then it SHOULD be used instead of defining a new derived
type. type.
If an appropriate units identifier can be associated with the desired If an appropriate units identifier can be associated with the desired
semantics, then a units statement SHOULD be present. semantics, then a units statement SHOULD be present.
If an appropriate default value can be associated with the desired If an appropriate default value can be associated with the desired
semantics, then a default statement SHOULD be present. semantics, then a default statement SHOULD be present.
skipping to change at page 21, line 45 skipping to change at page 28, line 5
anticipated that these data types will be reused by multiple modules, anticipated that these data types will be reused by multiple modules,
then these derived types SHOULD be contained in a separate module or then these derived types SHOULD be contained in a separate module or
submodule, to allow easier reuse without unnecessary coupling. submodule, to allow easier reuse without unnecessary coupling.
The description statement MUST be present. The description statement MUST be present.
If the type definition semantics are defined in an external document If the type 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 the reference statement MUST be present. then the reference statement MUST be present.
5.12. Data Definitions 5.13. Data Definitions
The description statement MUST be present in the following YANG The description statement MUST be present in the following YANG
statements: statements:
o anyxml o anyxml
o augment o augment
o choice o choice
skipping to change at page 23, line 11 skipping to change at page 29, line 17
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
describe the purpose of each one. describe the purpose of each one.
5.13. Operation Definitions 5.14. Operation Definitions
If the operation semantics are defined in an external document (other If the operation semantics are defined in an external document (other
than another YANG module indicated by an import statement), then a than another YANG module indicated by an import statement), then a
reference statement MUST be present. reference statement MUST be present.
If the operation impacts system behavior in some way, it SHOULD be If the operation impacts system behavior in some way, it SHOULD be
mentioned in the description statement. mentioned in the description statement.
If the operation is potentially harmful to system behavior in some If the operation is potentially harmful to system behavior in some
way, it MUST be mentioned in the Security Considerations section of way, it MUST be mentioned in the Security Considerations section of
the document. the document.
5.14. Notification Definitions 5.15. Notification Definitions
The description statement MUST be present. The description statement MUST be present.
If the notification semantics are defined in an external document If the notification 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.
If the notification refers to a specific resource instance, then this If the notification refers to a specific resource instance, then this
instance SHOULD be identified in the notification data. This is instance SHOULD be identified in the notification data. This is
usually done by including 'leafref' leaf nodes with the key leaf usually done by including 'leafref' leaf nodes with the key leaf
skipping to change at page 24, line 5 skipping to change at page 30, line 9
} }
} }
} }
Note that there are no formal YANG statements to identify any data Note that there are no formal YANG statements to identify any data
node resources associated with a notification. The description node resources associated with a notification. The description
statement for the notification SHOULD specify if and how the statement for the notification SHOULD specify if and how the
notification identifies any data node resources associated with the notification identifies any data node resources associated with the
specific event. specific event.
5.15. Feature Definitions 5.16. Feature Definitions
The YANG "feature" statement is used to define a label for a set of The YANG "feature" statement is used to define a label for a set of
optional functionality within a module. The "if-feature" statement optional functionality within a module. The "if-feature" statement
is used in the YANG statements associated with a feature. is used in the YANG statements associated with a feature.
The set of YANG features available in a module should be considered The set of YANG features available in a module should be considered
carefully. The description-stmt within a feature-stmt MUST specify carefully. The description-stmt within a feature-stmt MUST specify
any interactions with other features. any interactions with other features.
If there is a large set of objects associated with a YANG feature, If there is a large set of objects associated with a YANG feature,
then consider moving those objects to a separate module, instead of then consider moving those objects to a separate module, instead of
using a YANG feature. Note that the set of features within a module 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 is easily discovered by the reader, but the set of related modules
within the entire YANG library is not as easy to identity. Module within the entire YANG library is not as easy to identity. Module
names with a common prefix can help readers identity the set of names with a common prefix can help readers identity the set of
related modules, but this assumes the reader will have discovered and related modules, but this assumes the reader will have discovered and
installed all the relevant modules. installed all the relevant modules.
Another consideration for deciding whether to create a new module or
add a YANG feature is the stability of the module in question. It
may be desirable to have a stable base module that is not changed
frequently. If new functionality is placed in a separate module,
then the base module does not need to be republished. If it is
designed as a YANG feature then the module will need to be
republished.
If one feature requires implementation of another feature, then an If one feature requires implementation of another feature, then an
"if-feature" statement SHOULD be used in the dependent "feature" "if-feature" statement SHOULD be used in the dependent "feature"
statement. statement.
For example, feature2 requires implementation of feature1: For example, feature2 requires implementation of feature1:
feature feature1 { feature feature1 {
description "Some protocol feature"; description "Some protocol feature";
} }
feature feature2 { feature feature2 {
if-feature "feature1"; if-feature "feature1";
description "Another protocol feature"; description "Another protocol feature";
} }
5.16. Data Correlation 5.17. Augment Statements
The YANG "augment" statement is used to define a set of data
definition statements that will be added as child nodes of a target
data node. The module namespace for these data nodes will be the
augmenting module, not the augmented module.
A top-level "augment" statement SHOULD NOT be used if the target data
node is in the same module or submodule as the evaluated "augment"
statement. The data definition statements SHOULD be added inline
instead.
5.17.1. Conditional Augment Statements
The "augment" statement is often used together with the "when"
statement and/or "if-feature" statement to make the augmentation
conditional on some portion of the data model.
The following example from [RFC7223] shows how a conditional
container called "ethernet" is added to the "interface" list only for
entries of the type "ethernetCsmacd".
augment "/if:interfaces/if:interface" {
when "if:type = 'ianaift:ethernetCsmacd'";
container ethernet {
leaf duplex {
...
}
}
}
5.17.2. Conditionally Mandatory Data Definition Statements
YANG has very specific rules about how configuration data can be
updated in new releases of a module. These rules allow an "old
client" to continue interoperating with a "new server".
If data nodes are added to an existing entry, the old client MUST NOT
be required to provide any mandatory parameters that were not in the
original module definition.
It is possible to add conditional augment statements such that the
old client would not know about the new condition, and would not
specify the new condition. The conditional augment statement can
contain mandatory objects only if the condition is false unless
explicitly requested by the client.
Only a conditional augment statement that uses the "when" statement
form of condition can be used in this manner. The YANG features
enabled on the server cannot be controlled by the client in any way,
so it is not safe to add mandatory augmenting data nodes based on the
"if-feature" statement.
The XPath "when" statement condition MUST NOT reference data outside
of target data node because the client does not have any control over
this external data.
In the following dummy example, it is OK to augment the "interface"
entry with "mandatory-leaf" because the augmentation depends on
support for "some-new-iftype". The old client does not know about
this type so it would never select this type, and therefore not be
adding a mandatory data node.
module my-module {
...
identity some-new-iftype {
base iana:iana-interface-type;
}
augment "/if:interfaces/if:interface" {
when "if:type = 'mymod:some-new-iftype'";
leaf mandatory-leaf {
mandatory true;
...
}
}
}
Note that this practice is safe only for creating data resources. It
is not safe for replacing or modifying resources if the client does
not know about the new condition. The YANG data model MUST be
packaged in a way that requires the client to be aware of the
mandatory data nodes if it is aware of the condition for this data.
In the example above, the "some-new-iftype" identity is defined in
the same module as the "mandatory-leaf" data definition statement.
This practice is not safe for identities defined in a common module
such as "iana-if-type" because the client is not required to know
about "my-module" just because it knows about the "iana-if-type"
module.
5.18. Data Correlation
Data can be correlated in various ways, using common data types, Data can be correlated in various ways, using common data types,
common data naming, and common data organization. There are several common data naming, and common data organization. There are several
ways to extend the functionality of a module, based on the degree of ways to extend the functionality of a module, based on the degree of
coupling between the old and new functionality: coupling between the old and new functionality:
o inline: update the module with new protocol-accessible objects. o inline: update the module with new protocol-accessible objects.
The naming and data organization of the original objects is used. The naming and data organization of the original objects is used.
The new objects are in the original module namespace. The new objects are in the original module namespace.
o augment: create a new module with new protocol-accessible objects o augment: create a new module with new protocol-accessible objects
that augment the original data structure. The naming and data that augment the original data structure. The naming and data
organization of the original objects is used. The new objects are organization of the original objects is used. The new objects are
in the new module namespace. in the new module namespace.
o mirror: create new objects in a new module or the original module, 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 except use new a naming scheme and data location. The naming can
be coupled in different ways. Tight coupling is achieved with a be coupled in different ways. Tight coupling is achieved with a
"leafref" data type. This method SHOULD be used. If the new data "leafref" data type, with the "require-instance" sub-statement set
instances are not limited to the values in use in the original to "true". This method SHOULD be used.
data structure, then the "require-instance" sub-statement MUST be
set to "false". Loose coupling is achieved by using key leafs If the new data instances are not limited to the values in use in the
with the same data type as the original data structure. 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. This
has the same semantics as setting the "require-instance" sub-
statement to "false".
It is sometimes useful to separate configuration and operational It is sometimes useful to separate configuration and operational
state, so that they do not not even share the exact same naming state, so that they do not not even share the exact same naming
characteristics. The correlation between configuration the characteristics. The correlation between configuration the
operational state data that is affected by changes in configuration operational state data that is affected by changes in configuration
is a complex problem. There may not be a simple 1:1 relationship is a complex problem. There may not be a simple 1:1 relationship
between a configuration data node and an operational data node. between a configuration data node and an operational data node.
Further work is needed in YANG to clarify this relationship. Further work is needed in YANG to clarify this relationship.
Protocol work may also be needed to allow a client to retrieve this 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 type of information from a server. At this time the best practice is
to clearly document any relationship to other data structures in the to clearly document any relationship to other data structures in the
"description" statement. "description" statement.
5.19. Operational State
In YANG, any data that has a "config" statement value of "false"
could be considered operational state. The relationship between
configuration (i.e., "config" statement has a value of "true") and
operational state can be complex.
One challenge for client developers is determining if the configured
value is being used, which requires the developer to know which
operational state parameters are associated with the particular
configuration object (or group of objects).
The simplest interaction between configuration and operational state
is "none". For example, the arbitrary administrative name or
sequence number assigned to an access control rule. The configured
value is always the value that is being used by the system.
However, some configuration parameters interact with routing and
other signalling protocols, such that the operational value in use by
the system may not be the same as the configured value. Other
parameters specify the desired state, but environmental and other
factors can cause the actual state to be different.
For example a "temperature" configuration setting only represents the
desired temperature. An operational state parameter is needed that
reports the actual temperature in order to determine if the cooling
system is operating correctly. YANG has no mechanism other than the
"description" statement to associate the desired temperature and the
actual temperature.
Careful consideration needs to be given to the location of
operational state data. It can either be located within the
configuration subtree for which it applies, or it can be located
outside the particular configuration subtree. Placing operation
state within the configuration subtree is appropriate if the
operational values can only exist if the configuration exists.
The "interfaces" and "interfaces-state" subtrees defined in [RFC7223]
are an example of a complex relationship between configuration and
operational state. The operational values can include interface
entries that have been discovered or initialized by the system. An
interface may be in use that has not been configured at all.
Therefore, the operational state for an interface cannot be located
within the configuration for that same interface.
Sometimes the configured value represents some sort of procedure to
be followed, in which the system will select an actual value, based
on protocol negotiation.
leaf duplex-admin-mode {
type enumeration {
enum auto;
enum half;
enum full;
}
}
leaf duplex-oper-mode {
config false;
type enumeration {
enum half;
enum full;
}
}
For example a "duplex" mode configuration may be "auto" to auto-
negotiate the actual value to be used. The operational parameter
will never contain the value "auto". It will always contain the
result of the auto-negotiation, such as "half" or "full". This is
just one way in which the configuration data model is not exactly the
same as the operational data model. Another is if the detailed
properties of the data are different for configured vs. learned
entries.
If all the data model properties are aligned between configuration
and operational data, then it can be useful to define the
configuration parameters within a grouping, and then replicate that
grouping within the operational state portion of the data model.
grouping parms {
// do not use config-stmt in any of the nodes
// placed in this grouping
}
container foo {
uses parms; // these are all config=true by default
state {
config false; // only exists if foo config exists
uses parms;
}
}
Note that this mechanism can also be used if the configuration and
operational state data are in separate sub-trees:
container bar { // bar config can exist without bar-state
config true;
uses parms;
}
container bar-state { // bar-state can exist without bar
config false;
uses parms;
}
The need to replicate objects or define different operational state
objects depends on the data model. It is not possible to define one
approach that will be optimal for all data models. Designers SHOULD
describe the relationship in detail between configuration objects and
any associated operational state objects. The "description"
statements for both the configuration and the operational state
SHOULD be used for this purpose.
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 31, line 5 skipping to change at page 41, line 45
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 Clarified conditional key leaf nodes
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 Clarified use of mandatory nodes with conditional augmentations
o Clarified namespace and domain conventions for example modules
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 33, line 5 skipping to change at page 43, line 13
[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.
[RFC7223] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 7223, May 2014.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
A.1. 00 to 01 A.1. 02 to 03
o Updated draft based on github data tracker issues added by Benoit
Clause (Issues 12 - 18)
A.2. 01 to 02
o Updated draft based on mailing list comments.
A.3. 00 to 01
All issues from the issue tracker have been addressed. All issues from the issue tracker have been addressed.
https://github.com/netmod-wg/rfc6087bis/issues https://github.com/netmod-wg/rfc6087bis/issues
o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules
can use an Informative reference to this RFC for tree diagrams. can use an Informative reference to this RFC for tree diagrams.
Updated guidelines to reference this RFC when tree diagrams are Updated guidelines to reference this RFC when tree diagrams are
used used
 End of changes. 41 change blocks. 
74 lines changed or deleted 610 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/