--- 1/draft-ietf-netmod-rfc6087bis-01.txt 2015-04-24 15:14:59.195944478 -0700 +++ 2/draft-ietf-netmod-rfc6087bis-02.txt 2015-04-24 15:14:59.251945829 -0700 @@ -1,18 +1,18 @@ Network Working Group A. Bierman Internet-Draft YumaWorks -Intended status: Standards Track October 23, 2014 -Expires: April 26, 2015 +Intended status: Standards Track April 24, 2015 +Expires: October 26, 2015 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-rfc6087bis-01 + draft-ietf-netmod-rfc6087bis-02 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 26, 2015. + This Internet-Draft will expire on October 26, 2015. Copyright Notice - Copyright (c) 2014 IETF Trust and the persons identified as the + Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. 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 @@ -62,52 +62,55 @@ 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 9 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 9 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.7.2. Documents that Extend an Existing Namespace . . . . . 11 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 11 + 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 13 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 13 5.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 13 5.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.4. Conditional Statements . . . . . . . . . . . . . . . . . . 14 - 5.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 14 - 5.5.1. Function Library . . . . . . . . . . . . . . . . . . . 14 + 5.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 15 + 5.5.1. Function Library . . . . . . . . . . . . . . . . . . . 15 5.5.2. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.5.3. Types . . . . . . . . . . . . . . . . . . . . . . . . 16 - 5.5.4. Wildcards . . . . . . . . . . . . . . . . . . . . . . 16 + 5.5.4. Wildcards . . . . . . . . . . . . . . . . . . . . . . 17 5.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 17 - 5.7. Module Header, Meta, and Revision Statements . . . . . . . 17 - 5.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 18 - 5.9. Top-Level Data Definitions . . . . . . . . . . . . . . . . 19 + 5.7. Module Header, Meta, and Revision Statements . . . . . . . 18 + 5.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 19 + 5.9. Top-Level Data Definitions . . . . . . . . . . . . . . . . 20 5.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 20 5.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 21 5.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 21 - 5.13. Operation Definitions . . . . . . . . . . . . . . . . . . 22 - 5.14. Notification Definitions . . . . . . . . . . . . . . . . . 22 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 - 7.1. Security Considerations Section Template . . . . . . . . . 25 - 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27 - 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 28 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 - 10.1. Normative References . . . . . . . . . . . . . . . . . . . 29 - 10.2. Informative References . . . . . . . . . . . . . . . . . . 29 - Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 31 - A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 31 - Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 32 - Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 34 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 36 + 5.13. Operation Definitions . . . . . . . . . . . . . . . . . . 23 + 5.14. Notification Definitions . . . . . . . . . . . . . . . . . 23 + 5.15. Feature Definitions . . . . . . . . . . . . . . . . . . . 24 + 5.16. Data Correlation . . . . . . . . . . . . . . . . . . . . . 24 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 + 7.1. Security Considerations Section Template . . . . . . . . . 27 + 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 + 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 30 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 + 10.1. Normative References . . . . . . . . . . . . . . . . . . . 31 + 10.2. Informative References . . . . . . . . . . . . . . . . . . 31 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 33 + A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 33 + Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 34 + Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 36 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 38 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 [RFC6020] data models. YANG is used to define the data structures, protocol operations, and notification content @@ -134,20 +137,24 @@ identifiers and string values, or top-level mandatory nodes, that a compliant server is not required to support. Only constructs that all servers are required to support can be used in IETF YANG modules. This document defines usage guidelines related to the NETCONF operations layer and NETCONF content layer, as defined in [RFC6241]. These guidelines are intended to be used by authors and reviewers to improve the readability and interoperability of published YANG data models. + Note that this document is not a YANG tutorial and the reader is + expected to know the YANG data modeling language before using this + document. + 2. Terminology 2.1. Requirements Notation The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. RFC 2119 language is used here to express the views of the NETMOD working group regarding content for YANG modules. YANG modules @@ -265,20 +272,26 @@ // ... revision 2010-01-18 { description "Latest revision"; reference "RFC XXXX"; } // ... } + Note that this convention MUST NOT be used for example modules or + module fragments. + + [FIXME: should a new convention called be added for + YANG example modules?] + 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: A simplified graphical representation of the data model is used in @@ -337,21 +350,21 @@ 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 2010-06-16. Authors MUST check the + considerations template dated 2013-05-08. Authors MUST check the webpage at the URL listed above in case there is a more recent 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 @@ -407,20 +420,30 @@ For every normative reference statement that appears in a module contained in the specification, which identifies a separate document, a corresponding normative reference to that document SHOULD appear in the Normative References section. The reference SHOULD correspond to the specific document version actually used within the specification. If the reference statement identifies an informative reference, which identifies a separate document, a corresponding informative reference to that document MAY appear in the Informative References section. +4.9. Validation Tools + + All modules need to be validated before submission in an Internet + Draft. The 'pyang' YANG compiler is freely available from github: + + https://github.com/mbj4668/pyang + + If the 'pyang' compiler is used, then the "--ietf" command line + option SHOULD be used to identify any IETF guideline issues. + 5. YANG Usage Guidelines In general, modules in IETF Standards Track specifications MUST comply with all syntactic and semantic requirements of YANG [RFC6020]. The guidelines in this section are intended to supplement the YANG specification, which is intended to define a minimum set of conformance requirements. In order to promote interoperability and establish a set of practices based on previous experience, the following sections establish usage @@ -492,20 +515,31 @@ If any notification data, or any data definition, for a non- configuration data node is not mandatory, then the server may or may not be required to return an instance of this data node. If any conditional requirements exist for returning the data node in a notification payload or retrieval request, they MUST be documented somewhere. For example, a 'when' or 'if-feature' statement could apply to the data node, or the conditional requirements could be explained in a 'description' statement within the data node or one of its ancestors (if any). + If any 'if-feature' statements apply to a list node, then the same + 'if-feature' statements MUST apply to any key leaf nodes for the + list. There MUST NOT be any 'if-feature' statements applied to any + key leaf that do not also apply to the parent list node. + + There SHOULD NOT be any 'when' statements applied to a key leaf node. + It is possible that a 'when' statement for an ancestor node of a key + leaf will have the exact node-set result as the key leaf. In such as + case, the 'when' statement for the key leaf is redundant and SHOULD + be avoided. + 5.5. XPath Usage This section describes guidelines for using the XML Path Language [W3C.REC-xpath-19991116] (XPath) within YANG modules. 5.5.1. Function Library The 'position' and 'last' functions SHOULD NOT be used. This applies to implicit use of the 'position' function as well (e.g., '//chapter[42]'). A server is only required to maintain the relative @@ -526,36 +560,45 @@ to YANG because there is no 'lang' attribute set with the document. The YANG compiler SHOULD return 'false' for this function. The 'local-name', 'namespace-uri', 'name', 'string', and 'number' functions SHOULD NOT be used if the argument is a node-set. If so, the function result will be determined by the document order of the node-set. Since this order can be different on each server, the function results can also be different. Any function call that implicitly converts a node-set to a string will also have this issue. + The 'local-name' function SHOULD NOT be used to reference local names + outside of the YANG module defining the must or when expression + containing the 'local-name' function. Example of a local-name + function that should not be used: + + /*[local-name()='foo'] + 5.5.2. Axes The 'attribute' and 'namespace' axes are not supported in YANG, and MAY be empty in a NETCONF server implementation. The 'preceding', and 'following' axes SHOULD NOT be used. These constructs rely on XML document order within a NETCONF server configuration database, which may not be supported consistently or produce reliable results across implementations. Predicate expressions based on static node properties (e.g., element name or value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The 'preceding' and 'following' axes MAY be used if document order is not relevant to the outcome of the expression (e.g., check for global uniqueness of a parameter value). - The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used. + The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, + however they MAY be used if document order is not relevant to the + outcome of the expression. 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 'preceding-sibling' and 'following-sibling' axes MAY be used if they are evaluated in a context where the context node is a user-ordered 'list' or 'leaf-list'. 5.5.3. Types Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT @@ -708,22 +751,22 @@ A standard namespace statement value SHOULD have the following form: : The following URN prefix string SHOULD be used for published and unpublished YANG modules: urn:ietf:params:xml:ns:yang: - The following example URNs would be valid temporary namespace - statement values for Standards Track modules: + The following example URNs would be valid namespace statement values + for Standards Track modules: 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 Note that a different URN prefix string SHOULD be used for non- Standards-Track modules. The string SHOULD be selected according to the guidelines in [RFC6020]. @@ -737,26 +780,26 @@ http://example.com/ns/example-system 5.9. 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 considered carefully. It is often useful to define separate top- - level containers for configuration and non-configuration data. There - SHOULD only be one top-level data node defined in each YANG module - for all configuration data nodes, if any configuration data nodes are - defined at all. There MAY be one top-level data node defined in each - YANG module for all non-configuration data nodes, if any non- - configuration data nodes are defined at all. + 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 group SHOULD NOT be used because this may change over time. 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 required to provide a value. Top-level database data definitions MUST NOT be mandatory. If a @@ -856,20 +900,25 @@ If the data definition semantics are defined in an external document, (other than another YANG module indicated by an import statement), then a reference statement MUST be present. The 'anyxml' construct may be useful to represent an HTML banner containing markup elements, such as '<b>' and '</b>', and MAY be used in such cases. However, this construct SHOULD NOT be used if other YANG data node types can be used instead to represent the desired syntax and semantics. + It has been found that the 'anyxml' statement is not implemented + consistently across all servers. It is possible that mixed mode XML + will not be supported, or configuration anyxml nodes will not + supported. + If there are referential integrity constraints associated with the desired semantics that can be represented with XPath, then one or more 'must' statements SHOULD be present. For list and leaf-list data definitions, if the number of possible instances is required to be bounded for all implementations, then the max-elements statements SHOULD be present. If any 'must' or 'when' statements are used within the data definition, then the data definition description statement SHOULD @@ -903,20 +952,97 @@ notification interface-up { description "Sent when an interface is activated."; leaf name { type leafref { path "/if:interfaces/if:interface/if:name"; } } } + Note that there are no formal YANG statements to identify any data + node resources associated with a notification. The description + statement for the notification SHOULD specify if and how the + notification identifies any data node resources associated with the + specific event. + +5.15. Feature Definitions + + The YANG "feature" statement is used to define a label for a set of + optional functionality within a module. The "if-feature" statement + is used in the YANG statements associated with a feature. + + The set of YANG features available in a module should be considered + carefully. The description-stmt within a feature-stmt MUST specify + any interactions with other features. + + If there is a large set of objects associated with a YANG feature, + then consider moving those objects to a separate module, instead of + using a YANG feature. Note that the set of features within a module + is easily discovered by the reader, but the set of related modules + within the entire YANG library is not as easy to identity. Module + names with a common prefix can help readers identity the set of + related modules, but this assumes the reader will have discovered and + installed all the relevant modules. + + If one feature requires implementation of another feature, then an + "if-feature" statement SHOULD be used in the dependent "feature" + statement. + + For example, feature2 requires implementation of feature1: + + feature feature1 { + description "Some protocol feature"; + } + + feature feature2 { + if-feature "feature1"; + description "Another protocol feature"; + } + +5.16. Data Correlation + + Data can be correlated in various ways, using common data types, + common data naming, and common data organization. There are several + ways to extend the functionality of a module, based on the degree of + coupling between the old and new functionality: + + o inline: update the module with new protocol-accessible objects. + The naming and data organization of the original objects is used. + The new objects are in the original module namespace. + + o augment: create a new module with new protocol-accessible objects + that augment the original data structure. The naming and data + organization of the original objects is used. The new objects are + in the new module namespace. + + o mirror: create new objects in a new module or the original module, + except use new a naming scheme and data location. The naming can + be coupled in different ways. Tight coupling is achieved with a + "leafref" data type. This method SHOULD be used. If the new data + instances are not limited to the values in use in the original + data structure, then the "require-instance" sub-statement MUST be + set to "false". Loose coupling is achieved by using key leafs + with the same data type as the original data structure. + + It is sometimes useful to separate configuration and operational + state, so that they do not not even share the exact same naming + characteristics. The correlation between configuration the + operational state data that is affected by changes in configuration + is a complex problem. There may not be a simple 1:1 relationship + between a configuration data node and an operational data node. + Further work is needed in YANG to clarify this relationship. + Protocol work may also be needed to allow a client to retrieve this + type of information from a server. At this time the best practice is + to clearly document any relationship to other data structures in the + "description" statement. + 6. IANA Considerations 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. @@ -1043,31 +1169,40 @@ o Updated obsolete URLs for IETF resources o Changed top-level data node guideline o Clarified XPath usage for a literal value representing a YANG identity o Clarified XPath usage for a when-stmt + o Clarified XPath usage for 'proceeding-sibling' and + 'following-sibling' axes + o Added terminology guidelines o Added YANG tree diagram definition and guideline o Updated XPath guidelines for type conversions and function library usage. o Updated data types section o Updated notifications section + o Clarified conditional key leaf nodes + + o Clarify usage of 'uint64' and 'int64' data types + + o Added text on YANG feature usage + 10. References 10.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", RFC 2223, October 1997. @@ -1127,21 +1262,21 @@ 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 o Issue 2: XPath function restrictions: Added paragraphs in XPath - usage section for 'id', 'namesapce-uri', 'name', and 'lang' + usage section for 'id', 'namespace-uri', 'name', and 'lang' functions o Issue 3: XPath function document order issues: Added paragraph in XPath usage section about node-set ordering for 'local-name', 'namespace-uri', 'name', 'string' and 'number' functions. Also any function that implicitly converts a node-set to a string. o Issue 4: XPath preceding-sibling and following-sibling: Checked and text in XPath usage section already has proposed text from Lada.