--- 1/draft-ietf-netmod-rfc6087bis-04.txt 2015-10-19 14:15:58.794974459 -0700 +++ 2/draft-ietf-netmod-rfc6087bis-05.txt 2015-10-19 14:15:58.886976720 -0700 @@ -1,18 +1,18 @@ Network Working Group A. Bierman Internet-Draft YumaWorks -Intended status: Standards Track July 6, 2015 -Expires: January 7, 2016 +Intended status: Standards Track October 19, 2015 +Expires: April 21, 2016 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-rfc6087bis-04 + draft-ietf-netmod-rfc6087bis-05 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 January 7, 2016. + This Internet-Draft will expire on April 21, 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 @@ -60,79 +60,82 @@ 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 . . . . . . . . . . . . . . . . . . . . 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.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 . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 15 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 15 - 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . 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. 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. 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 + 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 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 @@ -353,25 +356,36 @@ If the module(s) defined by the specification imports definitions 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 - [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. + These modules SHOULD be written using the YANG syntax defined in + [I-D.ietf-netmod-rfc6020bis]. YANG 1.0 [RFC6020] MAY be used if no + YANG 1.1 constructs or semantics are needed in the module. + + 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. + + Note that all YANG statements within a YANG module are considered + normative, if the module itself is considered normative, and not an + example module. The use of keywords defined in [RFC2119] apply to + YANG description statements in normative modules exactly as they + would in any other normative section. + + Example YANG modules MUST NOT contain any normative text, including + any reserved words from [RFC2119]. 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 @@ -479,36 +493,47 @@ 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 - [I-D.ietf-netmod-rfc6020bis]. + Normative modules contained in Standards Track documents MUST be + named according to the guidelines in the IANA Considerations section + of [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. + Example modules are non-normative, and SHOULD be named with the + prefix "example-". + + It is suggested that a stable prefix be selected representing the + entire organization. All normative YANG modules published by the + IETF MUST begin with the prefix "ietf-". Another standards + organization, such as the IEEE, might use the prefix "ieee-" for all + YANG modules. + Once a module name is published, it MUST NOT be reused, even if the - RFC containing the module is reclassified to 'Historic' status. + RFC containing the module is reclassified to 'Historic' status. A + module name cannot be changed in YANG, and this would be treated as a + a new module, not a name change. 5.2. Prefixes All YANG definitions are scoped by the module containing the definition being referenced. This allows definitions from multiple modules to be used, even if the names are not unique. In the example below, the identifier "foo" is used in all 3 modules: module example-foo { namespace "http://example.com/ns/foo"; @@ -556,20 +581,24 @@ path expressions. o The local module prefix MUST be used instead of no prefix in all "default" statements for an "identityref" or "instance-identifier" data type o The lcaol module prefix MAY be used for references to typedefs, groupings, extensions, features, and identities defined in the module. + 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 between 1 and 64 characters in length. These include any construct 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 @@ -895,34 +924,36 @@ 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. 5.8. Module Header, Meta, and Revision Statements For published modules, the namespace MUST be a globally unique URI, as defined in [RFC3986]. This value is usually assigned by the IANA. The organization statement MUST be present. If the module is - contained in a document intended for Standards Track status, then the - organization SHOULD be the IETF working group chartered to write the - document. + contained in a document intended for IETF Standards Track status, + then the organization SHOULD be the IETF working group chartered to + write the document. For other standards organizations, a similar + approach is also suggested. The contact statement MUST be present. If the module is contained in a document intended for Standards Track status, then the working group web and mailing information MUST be present, and the main document author or editor contact information SHOULD be present. If additional authors or editors exist, their contact information MAY be present. In addition, the Area Director and other contact information MAY be present. - The description statement MUST be present. The appropriate IETF - Trust Copyright text MUST be present, as described in Section 4.1. + The description statement MUST be present. For modules published + within IETF documents, the appropriate IETF Trust Copyright text MUST + be present, as described in Section 4.1. If the module relies on information contained in other documents, which are not the same documents implied by the import statements present in the module, then these documents MUST be identified in the 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 @@ -1164,21 +1195,53 @@ anticipated that these data types will be reused by multiple modules, then these derived types SHOULD be contained in a separate module or submodule, to allow easier reuse without unnecessary coupling. The description statement MUST be present. If the type definition semantics are defined in an external document (other than another YANG module indicated by an import statement), then the reference statement MUST be present. -5.13. Data Definitions +5.13. Reusable Groupings + + A reusable grouping is a YANG grouping that can be imported by + another module, and is intended for use by other modules. This is + not the same as a grouping that is used within the module it is + defined, but happens to be exportable to another module because it is + defined at the top-level of the YANG module. + + The following guidelines apply to reusable groupings, in order to + make them as robust as possible: + + o Clearly identify the purpose of the grouping in the "description" + statement. + + o There are 5 different XPath contexts in YANG (rpc/input, rpc/ + output, notification, config=true data nodes, and all data nodes). + Clearly identify which XPath contexts are applicable or excluded + for the grouping. + + o Do not reference data outside the grouping in any "path", "must", + or "when" statements. + + o Do not include a "default" sub-statement on a leaf or choice + unless the value applies on all possible contexts. + + o Do not include a "config" sub-statement on a data node unless the + value applies on all possible contexts. + + o Clearly identify any external dependencies in the grouping + "description" statement, such as nodes referenced by absolute path + from a "path", "must", or "when" statement. + +5.14. Data Definitions The description statement MUST be present in the following YANG statements: o anyxml o augment o choice @@ -1224,34 +1286,42 @@ 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 describe the purpose of each one. -5.14. Operation Definitions + The "choice" statement is allowed to be directly present within a + "case" statement in YANG 1.1. This needs to be considered carefully. + Consider simply including the nested "choice" as additional "case" + statements within the parent "choice" statement. Note that the + "mandatory" and "default" statements within a nested "choice" + statement only apply if the "case" containing the nested "choice" + statement is first selected. + +5.15. Operation Definitions If the operation semantics are defined in an external document (other than another YANG module indicated by an import statement), then a reference statement MUST be present. If the operation impacts system behavior in some way, it SHOULD be mentioned in the description statement. If the operation is potentially harmful to system behavior in some way, it MUST be mentioned in the Security Considerations section of the document. -5.15. Notification Definitions +5.16. Notification Definitions The description statement MUST be present. If the notification semantics are defined in an external document (other than another YANG module indicated by an import statement), then a reference statement MUST be present. If the notification refers to a specific resource instance, then this instance SHOULD be identified in the notification data. This is usually done by including 'leafref' leaf nodes with the key leaf @@ -1265,21 +1335,21 @@ } } } 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.16. Feature Definitions +5.17. 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, @@ -1307,53 +1377,53 @@ feature feature1 { description "Some protocol feature"; } feature feature2 { if-feature "feature1"; description "Another protocol feature"; } -5.17. Augment Statements +5.18. Augment Statements The YANG "augment" statement is used to define a set of data definition statements that will be added as child nodes of a target data node. The module namespace for these data nodes will be the augmenting module, not the augmented module. A top-level "augment" statement SHOULD NOT be used if the target data node is in the same module or submodule as the evaluated "augment" statement. The data definition statements SHOULD be added inline instead. -5.17.1. Conditional Augment Statements +5.18.1. Conditional Augment Statements The "augment" statement is often used together with the "when" statement and/or "if-feature" statement to make the augmentation conditional on some portion of the data model. The following example from [RFC7223] shows how a conditional container called "ethernet" is added to the "interface" list only for entries of the type "ethernetCsmacd". augment "/if:interfaces/if:interface" { when "if:type = 'ianaift:ethernetCsmacd'"; container ethernet { leaf duplex { ... } } } -5.17.2. Conditionally Mandatory Data Definition Statements +5.18.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 @@ -1401,21 +1471,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.18. Deviation Statements +5.19. 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. @@ -1441,21 +1511,48 @@ } Correct: (max-elements in a deviation) deviation /bk:backups/bk:backup { deviate add { max-elements 10; } } -5.19. Data Correlation +5.20. 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 + normal YANG statements. + + o The module containing the extension statement MUST clearly + identify the conformance requirements for the extension. It + should be clear whether all implementations of the YANG module + containing the extension need to also implement the extension. If + 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 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. @@ -1482,21 +1579,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.20. Operational State +5.22. 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). @@ -1595,21 +1692,21 @@ } 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 +5.23. 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 @@ -1617,45 +1714,45 @@ 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 +5.24. YANG 1.1 Guidelines TODO: need more input on YANG 1.1 guidelines -5.22.1. Importing Multiple Revisions +5.24.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 +5.24.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 +5.24.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 + subtree of YANG data nodes. The "anydata" statement 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 @@ -1817,42 +1914,46 @@ 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. + draft-ietf-netmod-rfc6020bis-07 (work in progress), + September 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 @@ -1876,39 +1977,61 @@ [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. 03 ot 04 +A.1. 04 to 05 + + 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. + + o Added prefix value selection guidelines + + 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 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 +A.3. 02 to 03 o Updated draft based on github data tracker issues added by Benoit Clause (Issues 12 - 18) -A.3. 01 to 02 +A.4. 01 to 02 o Updated draft based on mailing list comments. -A.4. 00 to 01 +A.5. 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