--- 1/draft-ietf-netmod-yang-usage-07.txt 2010-07-08 22:12:22.000000000 +0200 +++ 2/draft-ietf-netmod-yang-usage-08.txt 2010-07-08 22:12:22.000000000 +0200 @@ -1,18 +1,18 @@ Internet Engineering Task Force A. Bierman Internet-Draft InterWorking Labs -Intended status: Informational June 23, 2010 -Expires: December 25, 2010 +Intended status: Informational July 8, 2010 +Expires: January 9, 2011 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-yang-usage-07 + draft-ietf-netmod-yang-usage-08 Abstract This memo provides guidelines for authors and reviewers of standards track specifications containing YANG data model modules. Applicable portions may be used as a basis for reviews of other YANG data model documents. Recommendations and procedures are defined, which are intended to increase interoperability and usability of NETCONF implementations which utilize YANG data model modules. @@ -24,21 +24,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 25, 2010. + This Internet-Draft will expire on January 9, 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 @@ -51,60 +51,61 @@ Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. General Documentation Guidelines . . . . . . . . . . . . . . . 7 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 7 - 3.2. Narrative Sections . . . . . . . . . . . . . . . . . . . . 7 + 3.2. Narrative Sections . . . . . . . . . . . . . . . . . . . . 8 3.3. Definitions Section . . . . . . . . . . . . . . . . . . . 8 3.4. Security Considerations Section . . . . . . . . . . . . . 8 - 3.5. IANA Considerations Section . . . . . . . . . . . . . . . 8 + 3.5. IANA Considerations Section . . . . . . . . . . . . . . . 9 3.5.1. Documents that Create a New Name Space . . . . . . . . 9 3.5.2. Documents that Extend an Existing Name Space . . . . . 9 - 3.6. Reference Sections . . . . . . . . . . . . . . . . . . . . 9 - 3.7. Intellectual Property Section . . . . . . . . . . . . . . 9 - 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 10 - 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 10 - 4.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 10 - 4.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 4.4. Conditional Statements . . . . . . . . . . . . . . . . . . 11 - 4.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 11 - 4.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 12 - 4.7. Module Header, Meta, and Revision Statements . . . . . . . 13 - 4.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 14 - 4.9. Top Level Data Definitions . . . . . . . . . . . . . . . . 15 - 4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 15 - 4.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 16 - 4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 16 - 4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 17 - 4.14. Notification Definitions . . . . . . . . . . . . . . . . . 18 - 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 - 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 - 8.1. Normative References . . . . . . . . . . . . . . . . . . . 22 - 8.2. Informative References . . . . . . . . . . . . . . . . . . 22 - Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 23 - Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 25 - Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 28 - C.1. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 28 - C.2. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 28 - C.3. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 28 - C.4. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 28 - C.5. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 29 - C.6. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 29 - C.7. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 30 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 31 + 3.6. Reference Sections . . . . . . . . . . . . . . . . . . . . 10 + 3.7. Intellectual Property Section . . . . . . . . . . . . . . 10 + 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 11 + 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 11 + 4.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 11 + 4.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 4.4. Conditional Statements . . . . . . . . . . . . . . . . . . 12 + 4.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 12 + 4.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 13 + 4.7. Module Header, Meta, and Revision Statements . . . . . . . 14 + 4.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 15 + 4.9. Top Level Data Definitions . . . . . . . . . . . . . . . . 16 + 4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 16 + 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 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. 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 @@ -216,24 +217,35 @@ 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 [I-D.ietf-netmod-yang]. - For example, if the latest revision date of the 'ietf-foo' module is - '2010-01-18', then the following '' line would be used: + 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 XXXXX"; + } + // ... + } + + + Figure 1 3.2. Narrative Sections The narrative part MUST include an overview section that describes the scope and field of application of the module(s) defined by the specification and that specifies the relationship (if any) of these modules to other standards, particularly to standards containing other YANG modules. The narrative part SHOULD include one or more sections to briefly describe the structure of the modules defined in the specification. @@ -256,29 +268,37 @@ these guidelines. See Section 4 for guidelines on YANG usage. 3.4. 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://www.ops.ietf.org/yang-security-considerations.txt). + http://www.ops.ietf.org/netconf/yang-security-considerations.txt). - In particular, writable data nodes that could be especially - disruptive if abused MUST be explicitly listed by name and the - associated security risks MUST be spelled out; similarly, 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. + In particular: + + o Writable data nodes that could be especially disruptive if abused + MUST be explicitly listed by name and the associated security + risks MUST be explained. + + o Readable data nodes that contain especially sensitive information + or that raise significant privacy concerns MUST be explicitly + listed by name and the reasons for the sensitivity/privacy + 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. 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 @@ -603,23 +623,20 @@ 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 string data types, data definition semantics SHOULD NOT rely on - preservation of leading and trailing whitespace characters. - 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. 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 @@ -749,21 +766,21 @@ | reference | RFCXXXX | +---------------+-------------------------------------------+ 6. Security Considerations This document defines documentation guidelines for NETCONF content defined with the YANG data modeling language. The guidelines for how to write a Security Considerations section for a YANG module are defined in the online document - http://www.ops.ietf.org/yang-security-considerations.txt + http://www.ops.ietf.org/netconf/yang-security-considerations.txt This document does not introduce any new or increased security risks into the management system. 7. Acknowledgments The structure and contents of this document are adapted from Guidelines for MIB Documents [RFC4181], by C. M. Heard. The working group thanks Martin Bjorklund and Juergen Schoenwaelder @@ -836,22 +853,22 @@ 3. IETF Trust Copyright -- verify that the draft has the appropriate text regarding the rights that document contributers provide to the IETF Trust [RFC5378]. Some guidelines related to this requirement are described in Section 3.1. The IETF Trust license policy (TLP) can be found at: http://trustee.ietf.org/docs/IETF-Trust-License-Policy.pdf 4. Security Considerations Section -- verify that the draft uses the - latest approved template from the OPS area web site - (http://www.ops.ietf.org/yang-security-considerations.txt) and + latest approved template from the OPS area web site (http:// + www.ops.ietf.org/netconf/yang-security-considerations.txt) and that the guidelines therein have been followed. 5. 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, @@ -982,58 +999,69 @@ // rpc statements // notification statements // DO NOT put deviation statements in a published module } - Figure 1 + Figure 2 Appendix C. Change Log -C.1. Changes from 06 to 07 +C.1. 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 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.2. Changes from 05 to 06 +C.3. Changes from 05 to 06 o Several clarifications and corrections, based on the AD review by Dan Romascanu. -C.3. Changes from 04 to 05 +C.4. 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.4. Changes from 03 to 04 +C.5. 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 @@ -1062,47 +1090,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.5. Changes from 02 to 03 +C.6. 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.6. Changes from 01 to 02 +C.7. 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.7. Changes from 00 to 01 +C.8. 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