--- 1/draft-ietf-netmod-rfc6087bis-03.txt 2015-07-06 10:16:06.930081930 -0700 +++ 2/draft-ietf-netmod-rfc6087bis-04.txt 2015-07-06 10:16:07.018084077 -0700 @@ -1,18 +1,18 @@ Network Working Group A. Bierman Internet-Draft YumaWorks -Intended status: Standards Track June 12, 2015 -Expires: December 14, 2015 +Intended status: Standards Track July 6, 2015 +Expires: January 7, 2016 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-rfc6087bis-03 + draft-ietf-netmod-rfc6087bis-04 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,21 +25,21 @@ 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 December 14, 2015. + This Internet-Draft will expire on January 7, 2016. Copyright Notice 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 @@ -55,21 +55,21 @@ 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.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 9 - 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 9 + 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.7.2. Documents that Extend an Existing Namespace . . . . . 11 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 11 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 12 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 13 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 13 @@ -95,50 +95,58 @@ 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 26 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 27 5.13. Data Definitions . . . . . . . . . . . . . . . . . . . . . 28 5.14. Operation Definitions . . . . . . . . . . . . . . . . . . 29 5.15. Notification Definitions . . . . . . . . . . . . . . . . . 29 5.16. Feature Definitions . . . . . . . . . . . . . . . . . . . 30 5.17. Augment Statements . . . . . . . . . . . . . . . . . . . . 31 5.17.1. Conditional Augment Statements . . . . . . . . . . . . 31 5.17.2. Conditionally Mandatory Data Definition Statements . . 31 - 5.18. Data Correlation . . . . . . . . . . . . . . . . . . . . . 33 - 5.19. Operational State . . . . . . . . . . . . . . . . . . . . 33 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 38 - 7.1. Security Considerations Section Template . . . . . . . . . 38 - 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40 - 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 41 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42 - 10.1. Normative References . . . . . . . . . . . . . . . . . . . 42 - 10.2. Informative References . . . . . . . . . . . . . . . . . . 42 - Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 44 - A.1. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . . 44 - A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . . 44 - A.3. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 44 - Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 46 - Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 48 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 50 + 5.18. Deviation Statements . . . . . . . . . . . . . . . . . . . 33 + 5.19. Data Correlation . . . . . . . . . . . . . . . . . . . . . 33 + 5.20. Operational State . . . . . . . . . . . . . . . . . . . . 34 + 5.21. Performance Considerations . . . . . . . . . . . . . . . . 37 + 5.22. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 37 + 5.22.1. Importing Multiple Revisions . . . . . . . . . . . . . 37 + 5.22.2. Using Feature Logic . . . . . . . . . . . . . . . . . 38 + 5.22.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 38 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 40 + 7.1. Security Considerations Section Template . . . . . . . . . 40 + 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42 + 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 43 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 44 + 10.1. Normative References . . . . . . . . . . . . . . . . . . . 44 + 10.2. Informative References . . . . . . . . . . . . . . . . . . 44 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 46 + A.1. 03 ot 04 . . . . . . . . . . . . . . . . . . . . . . . . . 46 + A.2. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . . 46 + A.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . . 46 + A.4. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 46 + Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 48 + Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 50 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 52 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 - used within a NETCONF server. A server that supports a particular - YANG module will support client NETCONF operation requests, as - indicated by the specific content defined in the YANG module. + documents containing [I-D.ietf-netmod-rfc6020bis] data models. YANG + is used to define the data structures, protocol operations, and + notification content used within a NETCONF server. A server that + supports a particular YANG module will support client NETCONF + operation requests, as indicated by the specific content defined in + the YANG module. This document is similar to the Structure of Management Information version 2 (SMIv2) usage guidelines specification [RFC4181] in intent and structure. However, since that document was written a decade after SMIv2 modules had been in use, it was published as a 'Best Current Practice' (BCP). This document is not a BCP, but rather an informational reference, intended to promote consistency in documents containing YANG modules. Many YANG constructs are defined as optional to use, such as the @@ -184,22 +192,22 @@ o capabilities o client o operation o server 2.3. YANG Terms - The following terms are defined in [RFC6020] and are not redefined - here: + The following terms are defined in [I-D.ietf-netmod-rfc6020bis] and + are not redefined here: o data node o module o namespace o submodule o version @@ -272,22 +280,23 @@ online at: http://trustee.ietf.org/license-info/ 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 [RFC6020]. The following - example is for the '2010-01-18' revision of the 'ietf-foo' module: + 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" module ietf-foo { // ... revision 2010-01-18 { description "Latest revision"; reference "RFC XXXX"; } // ... } @@ -336,34 +344,34 @@ 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. If the module(s) defined by the specification imports definitions - from other modules (except for those defined in the [RFC6020] or - [RFC6991] documents), or are always implemented in conjunction with - other modules, then those facts MUST be noted in the overview - section, as MUST be noted any special interpretations of definitions - in other modules. + from other modules (except for those defined in the + [I-D.ietf-netmod-rfc6020bis] or [RFC6991] documents), or are always + implemented in conjunction with other modules, then those facts MUST + be noted in the overview section, as MUST be noted any special + interpretations of definitions in other modules. 4.5. Definitions Section This section contains the module(s) defined by the specification. These modules MUST be written using the YANG syntax defined in - [RFC6020]. A YIN syntax version of the module MAY also be present in - the document. There MAY also be other types of modules present in - the document, such as SMIv2, which are not affected by these - guidelines. + [I-D.ietf-netmod-rfc6020bis]. A YIN syntax version of the module MAY + also be present in the document. There MAY also be other types of + modules present in the document, such as SMIv2, which are not + affected by these guidelines. See Section 5 for guidelines on YANG usage. 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 @@ -404,22 +412,22 @@ 4.7.1. Documents that Create a New Namespace If an Internet-Draft defines a new namespace that is to be administered by the IANA, then the document MUST include an IANA Considerations section that specifies how the namespace is to be administered. Specifically, if any YANG module namespace statement value contained in the document is not already registered with IANA, then a new YANG Namespace registry entry MUST be requested from the IANA. The - [RFC6020] specification includes the procedure for this purpose in - its IANA Considerations section. + [I-D.ietf-netmod-rfc6020bis] specification includes the procedure for + this purpose in its IANA Considerations section. 4.7.2. Documents that Extend an Existing Namespace It is possible to extend an existing namespace using a YANG submodule that belongs to an existing module already administered by IANA. In this case, the document containing the main module MUST be updated to use the latest revision of the submodule. 4.8. Reference Sections @@ -458,36 +466,36 @@ http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules can be extracted correctly. 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. + [I-D.ietf-netmod-rfc6020bis]. 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 guidelines for specific YANG constructs. Only guidelines that clarify or restrict the minimum conformance requirements are included here. 5.1. Module Naming Conventions Modules contained in Standards Track documents SHOULD be named according to the guidelines in the IANA Considerations section of - [RFC6020]. + [I-D.ietf-netmod-rfc6020bis]. A distinctive word or acronym (e.g., protocol name or working group acronym) SHOULD be used in the module name. If new definitions are being defined to extend one or more existing modules, then the same word or acronym should be reused, instead of creating a new one. All published module names MUST be unique. For a YANG module published in an RFC, this uniqueness is guaranteed by IANA. For unpublished modules, the authors need to check that no other work in progress is using the same module name. @@ -552,22 +560,22 @@ data type o The lcaol module prefix MAY be used for references to typedefs, groupings, extensions, features, and identities defined in the module. 5.3. Identifiers Identifiers for all YANG identifiers in published modules MUST be between 1 and 64 characters in length. These include any construct - specified as an 'identifier-arg-str' token in the ABNF in Section 12 - of [RFC6020]. + specified as an 'identifier-arg-str' token in the ABNF in Section 13 + of [I-D.ietf-netmod-rfc6020bis]. 5.3.1. Identifier Naming Conventions Identifiers SHOULD follow a consistent naming pattern throughout the module. Only lower-case letters, numbers, and dashes SHOULD be used in identifier names. Upper-case characters and the underscore character MAY be used if the identifier represents a well-known value that uses these characters. Identifiers SHOULD include complete words and/or well-known acronyms @@ -965,21 +973,21 @@ 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]. + the guidelines in [I-D.ietf-netmod-rfc6020bis]. The following examples are for non-Standards-Track modules. The domain "example.com" SHOULD be used in all namespace URIs for example modules. http://example.com/ns/example-interfaces http://example.com/ns/example-system 5.10. Top-Level Data Definitions @@ -1393,21 +1401,61 @@ packaged in a way that requires the client to be aware of the mandatory data nodes if it is aware of the condition for this data. In the example above, the "some-new-iftype" identity is defined in the same module as the "mandatory-leaf" data definition statement. This practice is not safe for identities defined in a common module such as "iana-if-type" because the client is not required to know about "my-module" just because it knows about the "iana-if-type" module. -5.18. Data Correlation +5.18. 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. + + It is suggested that deviation statements be defined in separate + modules from regular YANG definitions. This allows the deviations to + be platform-specific and/or temporary. + + The "max-elements" statement is intended to describe an architectural + limit to the number of list entries. It is not intended to describe + platform limitations. It is better to use a "deviation" statement + for the platforms that have a hard resource limit. + + Example documenting platform resource limits: + + Wrong: (max-elements in the list itself) + + container backups { + list backup { + ... + max-elements 10; + ... + } + } + + Correct: (max-elements in a deviation) + + deviation /bk:backups/bk:backup { + deviate add { + max-elements 10; + } + } + +5.19. 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. @@ -1434,21 +1482,21 @@ 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. -5.19. Operational State +5.20. Operational State In YANG, any data that has a "config" statement value of "false" could be considered operational state. The relationship between configuration (i.e., "config" statement has a value of "true") and operational state can be complex. One challenge for client developers is determining if the configured value is being used, which requires the developer to know which operational state parameters are associated with the particular configuration object (or group of objects). @@ -1547,20 +1595,69 @@ } The need to replicate objects or define different operational state objects depends on the data model. It is not possible to define one approach that will be optimal for all data models. Designers SHOULD describe the relationship in detail between configuration objects and any associated operational state objects. The "description" statements for both the configuration and the operational state SHOULD be used for this purpose. +5.21. 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" + set to true are generally more expensive than if + "require-instance" is set to false + +5.22. YANG 1.1 Guidelines + + TODO: need more input on YANG 1.1 guidelines + +5.22.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. + +5.22.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. + +5.22.3. anyxml vs. anydata + + The "anyxml" statement MUST NOT be used to represent a conceptual + subtree of YANG data nodes. The "anydata" statment MUST be used for + this purpose. + 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. @@ -1717,43 +1814,45 @@ o Added Identifier Naming Conventions o Clarified use of mandatory nodes with conditional augmentations o Clarified namespace and domain conventions for example modules 10. References 10.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-06 (work in progress), + July 2015. + [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. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide to the IETF Trust", BCP 78, RFC 5378, November 2008. [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, and Boilerplates", RFC 5741, December 2009. - [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the - Network Configuration Protocol (NETCONF)", RFC 6020, - October 2010. - [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, July 2013. [W3C.REC-xpath-19991116] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium @@ -1777,30 +1876,39 @@ [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG Data Model Documents", RFC 6087, January 2011. [RFC7223] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, May 2014. Appendix A. Change Log -- RFC Ed.: remove this section before publication. -A.1. 02 to 03 +A.1. 03 ot 04 + + 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.2. 02 to 03 o Updated draft based on github data tracker issues added by Benoit Clause (Issues 12 - 18) -A.2. 01 to 02 +A.3. 01 to 02 o Updated draft based on mailing list comments. -A.3. 00 to 01 +A.4. 00 to 01 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 @@ -1872,21 +1980,21 @@ o IANA Considerations section -- this section must always be present. For each module within the document, ensure that the IANA Considerations section contains entries for the following IANA registries: XML Namespace Registry: Register the YANG module namespace. YANG Module Registry: Register the YANG module name, prefix, namespace, and RFC number, according to the rules specified - in [RFC6020]. + in [I-D.ietf-netmod-rfc6020bis]. o References -- verify that the references are properly divided between normative and informative references, that RFC 2119 is included as a normative reference if the terminology defined therein is used in the document, that all references required by the boilerplate are present, that all YANG modules containing imported items are cited as normative references, and that all citations point to the most current RFCs unless there is a valid reason to do otherwise (for example, it is OK to include an informative reference to a previous version of a specification to