--- 1/draft-ietf-netmod-yang-usage-08.txt 2010-07-12 22:10:37.000000000 +0200 +++ 2/draft-ietf-netmod-yang-usage-09.txt 2010-07-12 22:10:37.000000000 +0200 @@ -1,44 +1,45 @@ Internet Engineering Task Force A. Bierman Internet-Draft InterWorking Labs -Intended status: Informational July 8, 2010 -Expires: January 9, 2011 +Intended status: Informational July 12, 2010 +Expires: January 13, 2011 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-yang-usage-08 + draft-ietf-netmod-yang-usage-09 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 NETCONF - implementations which utilize YANG data model modules. + intended to increase interoperability and usability of Network + Configuration Protocol (NETCONF) implementations which utilize YANG + data model modules. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. 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 9, 2011. + This Internet-Draft will expire on January 13, 2011. Copyright Notice Copyright (c) 2010 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 @@ -80,47 +81,55 @@ 4.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 17 4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 17 4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 18 4.14. Notification Definitions . . . . . . . . . . . . . . . . . 19 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.1. Normative References . . . . . . . . . . . . . . . . . . . 23 8.2. Informative References . . . . . . . . . . . . . . . . . . 23 - Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 24 - Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 26 - Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 29 - C.1. Changes from 07 to 08 . . . . . . . . . . . . . . . . . . 29 - C.2. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 29 - C.3. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 29 - C.4. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 29 - C.5. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 30 - C.6. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 30 - C.7. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 31 - C.8. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 31 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 32 + Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 25 + Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 27 + Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 30 + C.1. Changes from 08 to 09 . . . . . . . . . . . . . . . . . . 30 + C.2. Changes from 07 to 08 . . . . . . . . . . . . . . . . . . 30 + C.3. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 30 + C.4. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 30 + C.5. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 30 + C.6. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 31 + C.7. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 32 + C.8. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 32 + C.9. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 32 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 33 1. Introduction The standardization of network configuration interfaces for use with - the NETCONF [RFC4741] protocol requires a modular set of data models, - which can be reused and extended over time. + the Network Configuration Protocol (NETCONF) [RFC4741] 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 YANG [I-D.ietf-netmod-yang] data models. It is - similar to the 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. + documents containing YANG [I-D.ietf-netmod-yang] data models. YANG + is used to define the data structures, protocol operations, and + notification content used within a NETCONF server. A server which + 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 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 description statement. However, in order to maximize interoperability of NETCONF implementations utilizing YANG data models, it is desirable to define a set of usage guidelines which may require a higher level of compliance than the minimum level defined in the YANG specification. In addition, YANG allows constructs such as infinite length identifiers and string values, or top-level mandatory nodes, that a @@ -167,39 +176,44 @@ o data node o module o namespace o submodule o version + o YANG + + o YIN + Note that the term 'module' may be used as a generic term for a YANG module or submodule. When describing properties which are specific to submodules, the term 'submodule' is used instead. 2.4. Terms The following terms are used throughout this document: published: A stable release of a module or submodule, usually contained in an RFC. unpublished: An unstable release of a module or submodule, usually contained in an Internet-Draft. 3. General Documentation Guidelines YANG data model modules under review are likely to be contained in Internet-Drafts. All guidelines for Internet-Draft authors MUST be - followed. These guidelines are available online at: + followed. These guidelines are defined in [RFC2223] and updated in + [RFC5741]. Additional information is also available online at: http://www.rfc-editor.org/rfc-editor/instructions2authors.txt The following sections MUST be present in an Internet-Draft containing a module: o Narrative sections o Definitions section @@ -281,24 +295,24 @@ 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 concerns MUST be explained. - o Operations (i.e., 'rpc' statements) which are potentially harmful - to system behavior or that raise significant privacy concerns MUST - be explicitly listed by name and the reasons for the sensitivity/ - privacy concerns MUST be explained. + o Operations (i.e., YANG 'rpc' statements) which are potentially + harmful to system behavior or that raise significant privacy + concerns MUST be explicitly listed by name and the reasons for the + sensitivity/privacy concerns MUST be explained. 3.5. IANA Considerations Section In order to comply with IESG policy as set forth in http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is submitted to the IESG for publication which has action items for IANA MUST contain an IANA Considerations section. The requirements for this section vary depending what actions are required of the IANA. If there are no IANA considerations applicable to the document, then the IANA Considerations section is not required. Refer to the @@ -307,22 +321,22 @@ 3.5.1. Documents that Create a New Name Space If an Internet-Draft defines a new name space that is to be administered by the IANA, then the document MUST include an IANA Considerations section, that specifies how the name space 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 YANG - specification includes the procedure for this purpose in its IANA - Considerations section. + [I-D.ietf-netmod-yang] specification includes the procedure for this + purpose in its IANA Considerations section. 3.5.2. Documents that Extend an Existing Name Space It is possible to extend an existing namespace using a YANG submodule which 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. 3.6. Reference Sections @@ -368,21 +382,24 @@ Modules contained in standards track documents SHOULD be named according to the guidelines in the IANA considerations section of [I-D.ietf-netmod-yang]. 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. + 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. Once a module name is published, it MUST NOT be reused, even if the RFC containing the module is reclassified to 'Historic' status. 4.2. 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 [I-D.ietf-netmod-yang]. @@ -415,62 +432,62 @@ 4.4. Conditional Statements A module may be conceptually partitioned in several ways, using the 'if-feature' and/or 'when' statements. Data model designers need to carefully consider all modularity aspects, including the use of YANG conditional statements. If a data definition is optional, depending on server support for a NETCONF protocol capability, then a YANG 'feature' statement SHOULD - be defined to indicate the NETCONF capability is supported within the - data model. + be defined to indicate that the NETCONF capability is supported + within the data model. 4.5. XPath Usage This section describes guidelines for using the XML Path Language [W3C.REC-xpath-19991116] (XPath) within YANG modules. The 'attribute' and 'namespace' axes are not supported in YANG, and MAY be empty in a NETCONF server implementation. The 'position' and 'last' functions MAY be used with caution. A server is not required to maintain any particular XML document order for system-ordered data nodes. 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', 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., name, value, - ancestors, descendants) SHOULD be used instead. + expressions based on static node properties (e.g., element name or + value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The 'preceding-sibling' and 'following-sibling' axes MAY be used, with caution. A server is not required to maintain a persistent or deterministic XML document order, which will affect use of these axes. Implicit 'position' function calls within predicates MAY be used with - caution. (e.g., //chapter[42]). Note that a NETCONF server is only + caution. (e.g., '//chapter[42]'). Note that a NETCONF server is only required to maintain relative document order for related instances of a user-ordered list or leaf-list data definition (i.e., 'ordered-by' statement set to 'user'). Data nodes which use the 'int64' and 'uint64' built-in type MAY be - used with caution, within relational expressions. There are boundary - conditions in which the translation from the YANG 64-bit type to an - XPath number can cause incorrect results. Specifically, an XPath - double precision floating point number cannot represent very large - positive or negative 64-bit numbers because it only provides a total - precision of 53 bits. + used with caution, within 'RelationalExpr' expressions. There are + boundary conditions in which the translation from the YANG 64-bit + type to an XPath number can cause incorrect results. Specifically, + an XPath 'double' precision floating point number cannot represent + very large positive or negative 64-bit numbers because it only + provides a total precision of 53 bits. Data modelers need to be careful not to confuse the YANG value space and the XPath value space. The data types are not the same in both, and conversion between YANG and XPath data types SHOULD be considered carefully. Explicit XPath data type conversions MAY be used (e.g., 'string', 'boolean', or 'number' functions), instead of implicit XPath data type conversions. @@ -495,23 +512,23 @@ MUST be updated so that the main module revision date is equal or more recent than the revision date of any submodule which is (directly or indirectly) included by the main module. 4.7. 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 documented 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 standards-track status, then the + organization SHOULD be the IETF working group chartered to write the + document. 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 @@ -612,42 +629,42 @@ 4.10. Data Types Selection of an appropriate data type (i.e., built-in type, existing derived type, or new derived type) is very subjective and therefore few requirements can be specified on that subject. Data model designers SHOULD use the most appropriate built-in data type for the particular application. If extensibility of enumerated values is required, then the - identityref data type SHOULD be used instead of an enumeration or + 'identityref' data type SHOULD be used instead of an enumeration or other built-in type. For string data types, if a machine-readable pattern can be defined for the desired semantics, then one or more pattern statements SHOULD be present. For string data types, if the length of the string is required to be bounded in all implementations, then a length statement MUST be present. For numeric data types, if the values allowed by the intended semantics are different than those allowed by the unbounded intrinsic - data type (e.g., int32), then a range statement SHOULD be present. + data type (e.g., 'int32'), then a range statement SHOULD be present. The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 'int64') SHOULD NOT be used unless negative values are allowed for the desired semantics. - For enumeration or bits data types, the semantics for each enum or - bit SHOULD be documented. A separate description statement (within - each enum or bit statement) SHOULD be present. + For 'enumeration' or 'bits' data types, the semantics for each 'enum' + or 'bit' SHOULD be documented. A separate description statement + (within each 'enum' or 'bit' statement) SHOULD be present. 4.11. Reusable Type Definitions If an appropriate derived type exists in any standard module, such as [I-D.ietf-netmod-yang-types], 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. @@ -786,33 +803,39 @@ The working group thanks Martin Bjorklund and Juergen Schoenwaelder for their extensive reviews and contributions to this document. 8. References 8.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. + [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. [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. [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. + [W3C.REC-xpath-19991116] DeRose, S. and J. Clark, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, . [I-D.ietf-netmod-yang] Bjorklund, M., "YANG - A data modeling language for the Network Configuration Protocol (NETCONF)", draft-ietf-netmod-yang-13 (work in progress), June 2010. @@ -1003,65 +1026,69 @@ // DO NOT put deviation statements in a published module } Figure 2 Appendix C. Change Log -C.1. Changes from 07 to 08 +C.1. Changes from 08 to 09 + + o Clarifications and corrections to address Gen-ART review comments. + +C.2. Changes from 07 to 08 o Corrected YANG security considerations URL. o Expanded 'CODE BEGINS' example. o Added RPC operations to the security considerations guidelines section. o Removed guideline about leading and trailing whitespace. -C.2. Changes from 06 to 07 +C.3. Changes from 06 to 07 o Corrected title change bug; supposed to be page header instead. o Fixed typos added to last revision. o Added sentence to checklist to make sure text outside module contains citations for imports. -C.3. Changes from 05 to 06 +C.4. Changes from 05 to 06 o Several clarifications and corrections, based on the AD review by Dan Romascanu. -C.4. Changes from 04 to 05 +C.5. Changes from 04 to 05 o Changed 'object' terminology to 'data definition'. o Put XPath guidelines in separate section. o Clarified XPath usage for XML document order dependencies. o Updated guidelines to current conventions. o Added informative reference for IANA considerations guidelines and XML registry. o Updated IANA Considerations section to reserve the ietf-template module in the YANG Module Name Registry so it cannot be reused accidently. o Many other clarifications and fixed typos found in WGLC reviews. -C.5. Changes from 03 to 04 +C.6. Changes from 03 to 04 o Removed figure 1 to reduce duplication, just refer to 4741bis draft. o Fixed bugs and typos found in WGLC reviews. o Removed some guidelines and referring to YANG draft instead of duplicating YANG rules here. o Changed security guidelines so they refer to the IETF Trust TLP @@ -1090,47 +1117,47 @@ o Added guideline that strings should not rely on preservation of leading and trailing whitespace characters. o Relaxed some XPath and anyxml guidelines from SHOULD NOT or MUST NOT to MAY use with caution. o Updated the TLP text within the example module again. o Reversed order of change log so most recent entries are first. -C.6. Changes from 02 to 03 +C.7. Changes from 02 to 03 o Updated figure 1 to align with 4741bis draft. o Updated guidelines for import-by-revision and include-by-revision. o Added file name to code begins convention in ietf-template module. -C.7. Changes from 01 to 02 +C.8. Changes from 01 to 02 o Updated figure 1 per mailing list comments. o Updated suggested organization to include the working group name. o Updated ietf-template.yang to use new organization statement value. o Updated Code Component requirements as per new TLP. o Updated ietf-template.yang to use new Code Component begin and end markers. o Updated references to the TLP in a couple sections. o Change manager/agent terminology to client/server. -C.8. Changes from 00 to 01 +C.9. Changes from 00 to 01 o Added transport 'TLS' to figure 1. o Added note about RFC 2119 terminology. o Corrected URL for instructions to authors. o Updated namespace procedures section. o Updated guidelines on module contact, reference, and organization