--- 1/draft-ietf-netmod-rfc6087bis-05.txt 2016-03-20 14:18:56.659996819 -0700 +++ 2/draft-ietf-netmod-rfc6087bis-06.txt 2016-03-20 14:18:56.844001293 -0700 @@ -1,18 +1,18 @@ Network Working Group A. Bierman Internet-Draft YumaWorks -Intended status: Standards Track October 19, 2015 -Expires: April 21, 2016 +Intended status: Standards Track March 20, 2016 +Expires: September 21, 2016 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-rfc6087bis-05 + draft-ietf-netmod-rfc6087bis-06 Abstract This memo provides guidelines for authors and reviewers of Standards Track specifications containing YANG data model modules. Applicable portions may be used as a basis for reviews of other YANG data model documents. Recommendations and procedures are defined, which are intended to increase interoperability and usability of Network Configuration Protocol (NETCONF) implementations that utilize YANG data model modules. @@ -25,25 +25,25 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on April 21, 2016. + This Internet-Draft will expire on September 21, 2016. Copyright Notice - Copyright (c) 2015 IETF Trust and the persons identified as the + Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as @@ -53,89 +53,95 @@ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 7 4. General Documentation Guidelines . . . . . . . . . . . . . . . 8 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 + 4.1.1. Example Modules . . . . . . . . . . . . . . . . . . . 9 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 - 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 9 + 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 - 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10 - 4.6. Security Considerations Section . . . . . . . . . . . . . 10 - 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11 - 4.7.1. Documents that Create a New Namespace . . . . . . . . 11 + 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 11 + 4.6. Security Considerations Section . . . . . . . . . . . . . 11 + 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 12 + 4.7.1. Documents that Create a New Namespace . . . . . . . . 12 4.7.2. Documents that Extend an Existing Namespace . . . . . 12 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 12 - 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12 - 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 12 - 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 13 - 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 13 - 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 14 - 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 15 - 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 15 - 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 16 - 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 16 - 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 17 - 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 17 - 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 18 - 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 19 - 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 19 - 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 20 - 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 20 - 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 21 - 5.8. Module Header, Meta, and Revision Statements . . . . . . . 22 - 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 23 - 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 24 - 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 24 - 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 25 - 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 25 - 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 26 - - 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 27 - 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 28 - 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 28 - 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 30 - 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 30 - 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 31 - 5.18. Augment Statements . . . . . . . . . . . . . . . . . . . . 31 - 5.18.1. Conditional Augment Statements . . . . . . . . . . . . 32 - 5.18.2. Conditionally Mandatory Data Definition Statements . . 32 - 5.19. Deviation Statements . . . . . . . . . . . . . . . . . . . 33 - 5.20. Extension Statements . . . . . . . . . . . . . . . . . . . 34 - 5.21. Data Correlation . . . . . . . . . . . . . . . . . . . . . 35 - 5.22. Operational State . . . . . . . . . . . . . . . . . . . . 36 - 5.23. Performance Considerations . . . . . . . . . . . . . . . . 38 - 5.24. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 38 - 5.24.1. Importing Multiple Revisions . . . . . . . . . . . . . 39 - 5.24.2. Using Feature Logic . . . . . . . . . . . . . . . . . 39 - 5.24.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 39 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 41 - 7.1. Security Considerations Section Template . . . . . . . . . 41 - 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 - 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 44 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 - 10.1. Normative References . . . . . . . . . . . . . . . . . . . 45 - 10.2. Informative References . . . . . . . . . . . . . . . . . . 46 - Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 47 - A.1. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . . 47 - A.2. 03 ot 04 . . . . . . . . . . . . . . . . . . . . . . . . . 47 - A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . . 47 - A.4. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . . 47 - A.5. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 48 - Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 49 - Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 51 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 53 + 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 13 + 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 13 + 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14 + 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14 + 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16 + 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 16 + 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 17 + 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 17 + 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 18 + 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 18 + 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 19 + 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 20 + 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 21 + 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 21 + 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 22 + 5.8. Module Header, Meta, and Revision Statements . . . . . . . 23 + 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 24 + 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 25 + 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 25 + 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 26 + 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 26 + 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 27 + 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 28 + 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 29 + 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 29 + 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 31 + 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 31 + 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 32 + 5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 32 + 5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 32 + 5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 33 + 5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 33 + 5.19.1. Conditional Augment Statements . . . . . . . . . . . . 33 + 5.19.2. Conditionally Mandatory Data Definition Statements . . 34 + 5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 35 + 5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 36 + 5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 37 + 5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 38 + 5.24. Performance Considerations . . . . . . . . . . . . . . . . 40 + 5.25. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 40 + 5.25.1. Importing Multiple Revisions . . . . . . . . . . . . . 41 + 5.25.2. Using Feature Logic . . . . . . . . . . . . . . . . . 41 + 5.25.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 41 + 5.25.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 41 + 5.26. Updating YANG Modules (Published vs. Unpublished) . . . . 42 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 44 + 7.1. Security Considerations Section Template . . . . . . . . . 44 + 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46 + 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 47 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 + 10.1. Normative References . . . . . . . . . . . . . . . . . . . 49 + 10.2. Informative References . . . . . . . . . . . . . . . . . . 50 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 51 + A.1. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 51 + A.2. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 51 + A.3. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 52 + A.4. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 52 + A.5. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 52 + A.6. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 52 + Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 54 + Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 56 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 58 1. Introduction The standardization of network configuration interfaces for use with the Network Configuration Protocol [RFC6241] requires a modular set of data models, which can be reused and extended over time. This document defines a set of usage guidelines for Standards Track documents containing [I-D.ietf-netmod-rfc6020bis] data models. YANG is used to define the data structures, protocol operations, and @@ -287,33 +293,60 @@ Each YANG module or submodule contained within an Internet-Draft or RFC is considered to be a code component. The strings "" and "" MUST be used to identify each code component. The "" tag SHOULD be followed by a string identifying the file name specified in Section 5.2 of [I-D.ietf-netmod-rfc6020bis]. The following example is for the '2010-01-18' revision of the 'ietf-foo' module: - file "ietf-foo@2010-01-18.yang" + file "ietf-foo@2016-03-20.yang" module ietf-foo { - // ... - revision 2010-01-18 { + namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; + prefix "foo"; + organization "..."; + contact "..."; + description "..."; + revision 2016-03-20 { description "Latest revision"; reference "RFC XXXX"; } - // ... + // ... more statements } + - Note that this convention MUST NOT be used for example modules or - module fragments. +4.1.1. Example Modules + + Note that the convention MUST NOT be used for example + modules or module fragments. Instead the following convention is + defined for complete example modules: + + file "example-bar@2016-03-20.yang" + module example-bar { + // ... + revision 2016-03-20; + + // contains complete module example, intended to compile + // ... + } + + + YANG module fragments MUST NOT use the or conventions, in order to make sure module extraction tools + will ignore them: + + leaf last-change-time { + type yang:date-and-time; + ... + } 4.2. Terminology Section A terminology section MUST be present if any terms are defined in the document or if any terms are imported from other documents. If YANG tree diagrams are used, then a sub-section explaining the YANG tree diagram syntax MUST be present, containing the following text: @@ -577,21 +610,21 @@ 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, + o The local module prefix MAY be used for references to typedefs, groupings, extensions, features, and identities defined in the module. Prefix values SHOULD be short, but also likely to be unique. Prefix values SHOULD NOT conflict with known modules that have been previously published. 5.3. Identifiers Identifiers for all YANG identifiers in published modules MUST be @@ -907,21 +940,21 @@ 'obsolete'. The status SHOULD NOT be changed from 'current' directly to 'obsolete'. An object SHOULD be available for at least one year with 'deprecated' status before it is changed to 'obsolete'. The module or submodule name MUST NOT be changed, once the document containing the module or submodule is published. The module namespace URI value MUST NOT be changed, once the document containing the module is published. - The revision-date substatement within the imports statement SHOULD be + The revision-date substatement within the import statement SHOULD be present if any groupings are used from the external module. The revision-date substatement within the include statement SHOULD be present if any groupings are used from the external submodule. If submodules are used, then the document containing the main module 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 or indirectly) included by the main module. @@ -1020,21 +1053,21 @@ http://example.com/ns/example-interfaces http://example.com/ns/example-system 5.10. Top-Level Data Definitions The top-level data organization SHOULD be considered carefully, in advance. Data model designers need to consider how the functionality 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 data SHOULD be considered carefully. It is often useful to define separate top- level containers for configuration and non-configuration data. The number of top-level data nodes within a module SHOULD be minimized. It is often useful to retrieve related information within a single subtree. If data is too distributed, is becomes difficult to retrieve all at once. The names and data organization SHOULD reflect persistent information, such as the name of a protocol. The name of the working @@ -1377,53 +1410,84 @@ feature feature1 { description "Some protocol feature"; } feature feature2 { if-feature "feature1"; description "Another protocol feature"; } -5.18. Augment Statements +5.18. YANG Data Node Constraints + +5.18.1. Controlling Quantity + + The "min-elements" and "max-elements" statements can be use to + control how many list or leaf-list instances are required for a + particular data node. YANG constraint statements SHOULD be used to + identify conditions that apply to all implementations of the data + model. If platform-specific limitations (e.g., the "max-elements" + supported for a particular list) are relevant to operations, then a + data model definition statement (e.g., "max-ports" leaf) SHOULD be + used to identify the limit. + +5.18.2. must vs. when + + The "must" and "when" YANG statements are used to provide cross- + object referential tests. They have very different behavior. The + "when" statement causes data node instances to be silently deleted as + soon as the condition becomes false. A false "when" expression is + not considered to be an error. + + The "when" statement SHOULD be used together with the "augment" or + "uses" statements to achieve conditional model composition. The + condition SHOULD be based on static properties of the augmented entry + (e.g., list key leafs). + + The "must" statement causes a datastore validation error if the + condition is false. This statement SHOULD be used for enforcing + parameter value restrictions that involve more than one data node + (e.g., end-time parameter must be after the start-time parameter). + +5.19. 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.18.1. Conditional Augment Statements +5.19.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.18.2. Conditionally Mandatory Data Definition Statements +5.19.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 @@ -1441,22 +1505,26 @@ 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 { - ... + module example-module { + namespace "http://example.com/ns/example-module"; + prefix mymod; + + import iana-if-type { prefix iana; } + import ietf-interfaces { prefix if; } 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; @@ -1471,21 +1539,21 @@ 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.19. Deviation Statements +5.20. Deviation Statements The YANG "deviation" statement cannot appear in IETF YANG modules, but it can be useful for documenting server capabilities. Deviation statements are not reusable and typically not shared across all platforms. There are several reasons that deviations might be needed in an implementation, e.g., an object cannot be supported on all platforms, or feature delivery is done in multiple development phases. @@ -1511,21 +1579,21 @@ } Correct: (max-elements in a deviation) deviation /bk:backups/bk:backup { deviate add { max-elements 10; } } -5.20. Extension Statements +5.21. Extension Statements The YANG "extension" statement is used to specify external definitions. This appears in the YANG syntax as an "unknown-statement". Usage of extension statements in a published module needs to be considered carefully. The following guidelines apply to the usage of YANG extensions: o The semantics of the extension MUST NOT contradict any YANG statements. Extensions can add semantics not covered by the @@ -1538,21 +1606,21 @@ not, identify what conditions apply that would require implementation of the extension. o The extension MUST clearly identify where it can be used within other YANG statements. o The extension MUST clearly identify if YANG statements or other extensions are allowed or required within the extension as sub- statements. -5.21. Data Correlation +5.22. 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. @@ -1568,74 +1636,75 @@ to "true". 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. This has the same semantics as setting the "require-instance" sub- statement to "false". It is sometimes useful to separate configuration and operational - state, so that they do not not even share the exact same naming + data, 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. + operational 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. -5.22. Operational State +5.23. Operational Data In YANG, any data that has a "config" statement value of "false" - could be considered operational state. The relationship between + could be considered operational data. The relationship between configuration (i.e., "config" statement has a value of "true") and - operational state can be complex. + operational data 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 + operational data 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. + In the simplest use-cases , there is no interaction between + configuration and operational data. 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 + desired temperature. An operational data 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. + operational 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 operational data 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 + operational data. 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 + Therefore, the operational data 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; @@ -1656,105 +1725,177 @@ 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 within the operational data 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: + operational 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 + The need to replicate objects or define different operational data 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. + any associated operational data objects. The "description" + statements for both the configuration and the operational data SHOULD + be used for this purpose. -5.23. Performance Considerations +5.24. Performance Considerations It is generally likely that certain YANG statements require more runtime resources than other statements. Although there are no performance requirements for YANG validation, the following information MAY be considered when designing YANG data models: o Lists are generally more expensive than containers o "when-stmt" evaluation is generally more expensive than "if-feature" or "choice" statements o "must" statement is generally more expensive than "min-entries", "max-entries", "mandatory", or "unique" statements o "identityref" leafs are generally more expensive than "enumeration" leafs - o "leafref" and "instance-identifier" types with "requite-instance" + o "leafref" and "instance-identifier" types with "require-instance" set to true are generally more expensive than if "require-instance" is set to false -5.24. YANG 1.1 Guidelines +5.25. YANG 1.1 Guidelines - TODO: need more input on YANG 1.1 guidelines + The set of YANG 1.1 guidelines will grow as operational experience is + gained with the new language features. This section contains an + initial set of guidelines. -5.24.1. Importing Multiple Revisions +5.25.1. Importing Multiple Revisions Standard modules SHOULD NOT import multiple revisions of the same module into a module. This MAY be done if the authors can - demonstrate that the "avoided" definitions from most recent of the - multiple revisions are somehow broken or harmful to interoperability. + demonstrate that the "avoided" definitions from the most recent of + the multiple revisions are somehow broken or harmful to + interoperability. -5.24.2. Using Feature Logic +5.25.2. Using Feature Logic The YANG 1.1 feature logic is much more expressive than YANG 1.0. A "description" statement SHOULD describe the "if-feature" logic in text, to help readers understand the module. YANG features SHOULD be used instead of the "when" statement, if - possible. This reduces server implementation complexity and might - reduce runtime resource requirements as well. + possible. Features are advertised by the server and objects + conditional by if-feature are conceptually grouped together. There + is no such commonality supported for "when" statements. -5.24.3. anyxml vs. anydata + Features generally require less server implementation complexity and + runtime resources than objects that use "when" statements. Features + are generally static (i.e., set when module is loaded and not changed + at runtime). However every client edit might cause a "when" + statement result to change. + +5.25.3. anyxml vs. anydata The "anyxml" statement MUST NOT be used to represent a conceptual subtree of YANG data nodes. The "anydata" statement MUST be used for this purpose. +5.25.4. action vs. rpc + + The use of "action" statements or "rpc" statements is a subjective + design decision. RPC operations are not associated with any + particular data node. Actions are associated with a specific data + node definition. An "action" statement SHOULD be used if the + protocol operation is specific to a subset of all data nodes instead + of all possible data nodes. + + The same action name MAY be used in different definitions within + different data node. For example, a "reset" action defined with a + data node definition for an interface might have different parameters + than for a power supply or a VLAN. The same action name SHOULD be + used to represent similar semantics. + + The NETCONF Access Control Model (NACM) [RFC6536] does not support + parameter access control for RPC operations. The user is given + permission (or not) to invoke the RPC operation with any parameters. + For example, if each client is only allowed to reset their own + interface, then NACM cannot be used. + + For example, NACM cannot enforce access access control based on the + value of the "interface" parameter, only the "reset" operation + itself: + + rpc reset { + input { + leaf interface { + type if:interface-ref; + mandatory true; + description "The interface to reset."; + } + } + } + + However, NACM can enforce access access control for individual + interface instances, using a "reset" action, If the user does not + have read access to the specific "interface" instance, then it cannot + invoke the "reset" action for that interface instance: + + container interfaces { + list interface { + ... + action reset { } + } + } + +5.26. Updating YANG Modules (Published vs. Unpublished) + + YANG modules can change over time. Typically, new data model + definitions are needed to support new features. YANG update rules + defined in section 11 of [I-D.ietf-netmod-rfc6020bis] MUST be + followed for published modules. They MAY be followed for unpublished + modules. + + The YANG update rules only apply to published module revisions. Each + organization will have their own way to identity published work which + is considered to be stable, and unpublished work which is considered + to be unstable. For example, in the IETF, the RFC document is used + for published work, and the Internet-Draft is used for unpublished + work. + 6. IANA Considerations This document registers one URI in the IETF XML registry [RFC3688]. The following registration has been made: URI: urn:ietf:params:xml:ns:yang:ietf-template Registrant Contact: The NETMOD WG of the IETF. @@ -1907,20 +2048,25 @@ o Clarify usage of 'uint64' and 'int64' data types 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 + o Added and convention + o Added YANG 1.1 guidelines + + o Added Data Model Constraints section + 10. References 10.1. Normative References [I-D.ietf-netmod-rfc6020bis] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", draft-ietf-netmod-rfc6020bis-07 (work in progress), September 2015. @@ -1970,28 +2116,52 @@ [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB Documents", BCP 111, RFC 4181, September 2005. [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG Data Model Documents", RFC 6087, January 2011. + [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration + Protocol (NETCONF) Access Control Model", RFC 6536, + March 2012. + [RFC7223] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, May 2014. Appendix A. Change Log -- RFC Ed.: remove this section before publication. -A.1. 04 to 05 +A.1. v05 to v06 + + o Changed example 'my-module' to 'example-module' + + o Added section Updating YANG Modules (Published vs. Unpublished) + + o Added Example Modules section + + o Added "" convention for full example modules + + o Added section on using action vs. rpc + + o Changed term "operational state" to "operational data" + + o Added section on YANG Data Node Constraints + + o Added guidelines on using must vs. when statements + + o Made ietf-foo module validate for I-D submission + +A.2. v04 to v05 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if no YANG 1.1 features needed o Changed SHOULD follow YANG naming conventions to MUST follow (for standards track documents only) o Clarified module naming conventions for normative modules, example modules, and modules from other SDOs. @@ -1999,39 +2169,39 @@ o Added new section on guidelines for reusable groupings o Made header guidelines less IETF-specific o Added new section on guidelines for extension statements o Added guidelines for nested "choice" statement within a "case" statement -A.2. 03 ot 04 +A.3. v03 ot v04 o Added sections for deviation statements and performance considerations o Added YANG 1.1 section o Updated YANG reference from 1.0 to 1.1 -A.3. 02 to 03 +A.4. v02 to v03 o Updated draft based on github data tracker issues added by Benoit Clause (Issues 12 - 18) -A.4. 01 to 02 +A.5. v01 to v02 o Updated draft based on mailing list comments. -A.5. 00 to 01 +A.6. v00 to v01 All issues from the issue tracker have been addressed. https://github.com/netmod-wg/rfc6087bis/issues o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules can use an Informative reference to this RFC for tree diagrams. Updated guidelines to reference this RFC when tree diagrams are used @@ -2148,21 +2318,21 @@ Checking for correct syntax, however, is only part of the job. It is just as important to actually read the YANG module document from the point of view of a potential implementor. It is particularly important to check that description statements are sufficiently clear and unambiguous to allow interoperable implementations to be created. Appendix C. YANG Module Template - file "ietf-template@2010-05-18.yang" + file "ietf-template@2016-03-20.yang" module ietf-template { // replace this string with a unique namespace URN value namespace "urn:ietf:params:xml:ns:yang:ietf-template"; // replace this string, and try to pick a unique prefix prefix "temp"; @@ -2206,25 +2376,25 @@ the RFC itself for full legal notices."; // RFC Ed.: replace XXXX with actual RFC number and remove // this note reference "RFC XXXX"; // RFC Ed.: remove this note // Note: extracted from RFC XXXX - // replace '2010-05-18' with the module publication date + // replace '2016-03-20' with the module publication date // The format is (year-month-day) - revision "2010-05-18" { - description - "Initial version"; + revision "2016-03-20" { + description "what changed in this revision"; + reference "document containing this module"; } // extension statements // feature statements // identity statements // typedef statements