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