draft-ietf-netmod-yang-usage-06.txt   draft-ietf-netmod-yang-usage-07.txt 
Internet Engineering Task Force A. Bierman Internet Engineering Task Force A. Bierman
Internet-Draft InterWorking Labs Internet-Draft InterWorking Labs
Intended status: Informational June 22, 2010 Intended status: Informational June 23, 2010
Expires: December 24, 2010 Expires: December 25, 2010
Guidelines for YANG Documents Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-yang-usage-06 draft-ietf-netmod-yang-usage-07
Abstract Abstract
This memo provides guidelines for authors and reviewers of standards This memo provides guidelines for authors and reviewers of standards
track specifications containing YANG data model modules. Applicable track specifications containing YANG data model modules. Applicable
portions may be used as a basis for reviews of other YANG data model portions may be used as a basis for reviews of other YANG data model
documents. Recommendations and procedures are defined, which are documents. Recommendations and procedures are defined, which are
intended to increase interoperability and usability of NETCONF intended to increase interoperability and usability of NETCONF
implementations which utilize YANG data model modules. implementations which utilize YANG data model modules.
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 24, 2010. This Internet-Draft will expire on December 25, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 48 skipping to change at page 2, line 48
4.14. Notification Definitions . . . . . . . . . . . . . . . . . 18 4.14. Notification Definitions . . . . . . . . . . . . . . . . . 18
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22
8.1. Normative References . . . . . . . . . . . . . . . . . . . 22 8.1. Normative References . . . . . . . . . . . . . . . . . . . 22
8.2. Informative References . . . . . . . . . . . . . . . . . . 22 8.2. Informative References . . . . . . . . . . . . . . . . . . 22
Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 23 Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 23
Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 25 Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 25
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 28 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 28
C.1. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 28 C.1. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 28
C.2. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 28 C.2. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 28
C.3. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 28 C.3. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 28
C.4. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 29 C.4. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 28
C.5. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 29 C.5. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 29
C.6. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 30 C.6. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 29
C.7. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 30
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 31 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 31
1. Introduction 1. Introduction
The standardization of network configuration interfaces for use with The standardization of network configuration interfaces for use with
the NETCONF [RFC4741] protocol requires a modular set of data models, the NETCONF [RFC4741] protocol requires a modular set of data models,
which can be reused and extended over time. which can be reused and extended over time.
This document defines a set of usage guidelines for standards track This document defines a set of usage guidelines for standards track
documents containing YANG [I-D.ietf-netmod-yang] data models. It is documents containing YANG [I-D.ietf-netmod-yang] data models. It is
skipping to change at page 8, line 20 skipping to change at page 8, line 20
documents), or are always implemented in conjunction with other documents), or are always implemented in conjunction with other
modules, then those facts MUST be noted in the overview section, as modules, then those facts MUST be noted in the overview section, as
MUST be noted any special interpretations of definitions in other MUST be noted any special interpretations of definitions in other
modules. modules.
3.3. Definitions Section 3.3. Definitions Section
This section contains the module(s) defined by the specification. This section contains the module(s) defined by the specification.
These modules MUST be written using the YANG syntax defined in These modules MUST be written using the YANG syntax defined in
[I-D.ietf-netmod-yang]. A YIN syntax version of the module MAY also [I-D.ietf-netmod-yang]. A YIN syntax version of the module MAY also
be present in the document. 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 4 for guidelines on YANG usage. See Section 4 for guidelines on YANG usage.
3.4. Security Considerations Section 3.4. Security Considerations Section
Each specification that defines one or more modules MUST contain a Each specification that defines one or more modules MUST contain a
section that discusses security considerations relevant to those section that discusses security considerations relevant to those
modules. This section MUST be patterned after the latest approved modules. This section MUST be patterned after the latest approved
template (available at template (available at
http://www.ops.ietf.org/yang-security-considerations.txt). http://www.ops.ietf.org/yang-security-considerations.txt).
skipping to change at page 15, line 45 skipping to change at page 15, line 45
type for the particular application. type for the particular application.
If extensibility of enumerated values is required, then the 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. other built-in type.
For string data types, if a machine-readable pattern can be defined For string data types, if a machine-readable pattern can be defined
for the desired semantics, then one or more pattern statements SHOULD for the desired semantics, then one or more pattern statements SHOULD
be present. be present.
For string data types, if the length of the string is required to For string data types, if the length of the string is required to be
bounded in all implementations, then a length statement MUST be bounded in all implementations, then a length statement MUST be
present. present.
For string data types, data definition semantics SHOULD NOT rely on For string data types, data definition semantics SHOULD NOT rely on
preservation of leading and trailing whitespace characters. preservation of leading and trailing whitespace characters.
For numeric data types, if the values allowed by the intended For numeric data types, if the values allowed by the intended
semantics are different than those allowed by the unbounded intrinsic 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.
skipping to change at page 24, line 9 skipping to change at page 24, line 9
6. References -- verify that the references are properly divided 6. References -- verify that the references are properly divided
between normative and informative references, that RFC 2119 is between normative and informative references, that RFC 2119 is
included as a normative reference if the terminology defined included as a normative reference if the terminology defined
therein is used in the document, that all references required by therein is used in the document, that all references required by
the boilerplate are present, that all YANG modules containing the boilerplate are present, that all YANG modules containing
imported items are cited as normative references, and that all imported items are cited as normative references, and that all
citations point to the most current RFCs unless there is a valid citations point to the most current RFCs unless there is a valid
reason to do otherwise (for example, it is OK to include an reason to do otherwise (for example, it is OK to include an
informative reference to a previous version of a specification to informative reference to a previous version of a specification to
help explain a feature included for backward compatibility). help explain a feature included for backward compatibility). Be
sure citations for all imported modules are present somewhere in
the document text (outside the YANG module).
7. Copyright Notices -- verify that the draft contains an 7. Copyright Notices -- verify that the draft contains an
abbreviated IETF Trust copyright notice in the description abbreviated IETF Trust copyright notice in the description
statement of each YANG module or sub-module, and that it contains statement of each YANG module or sub-module, and that it contains
the full IETF Trust copyright notice at the end of the document. the full IETF Trust copyright notice at the end of the document.
Make sure that the correct year is used in all copyright dates. Make sure that the correct year is used in all copyright dates.
Use the approved text from the latest Trust Legal Provisions Use the approved text from the latest Trust Legal Provisions
(TLP) document, which can be found at: (TLP) document, which can be found at:
http://trustee.ietf.org/license-info/ http://trustee.ietf.org/license-info/
8. Other Issues -- check for any issues mentioned in 8. Other Issues -- check for any issues mentioned in
http://www.ietf.org/ID-Checklist.html that are not covered http://www.ietf.org/ID-Checklist.html that are not covered
elsewhere. elsewhere.
9. Technical Content -- review the actual technical content for 9. Technical Content -- review the actual technical content for
compliance with the guidelines in this document. The use of a compliance with the guidelines in this document. The use of a
YANG module compiler is RECOMMENDED when checking for syntax YANG module compiler is recommended when checking for syntax
errors. A list of freely available tools and other information errors. A list of freely available tools and other information
can be found at: can be found at:
http://trac.tools.ietf.org/wg/netconf/trac/wiki http://trac.tools.ietf.org/wg/netconf/trac/wiki
Checking for correct syntax, however, is only part of the job. Checking for correct syntax, however, is only part of the job.
It is just as important to actually read the YANG module document It is just as important to actually read the YANG module document
from the point of view of a potential implementor. It is from the point of view of a potential implementor. It is
particularly important to check that description statements are particularly important to check that description statements are
sufficiently clear and unambiguous to allow interoperable sufficiently clear and unambiguous to allow interoperable
skipping to change at page 28, line 7 skipping to change at page 28, line 7
// DO NOT put deviation statements in a published module // DO NOT put deviation statements in a published module
} }
<CODE ENDS> <CODE ENDS>
Figure 1 Figure 1
Appendix C. Change Log Appendix C. Change Log
C.1. Changes from 05 to 06 C.1. 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
o Several clarifications and corrections, based on the AD review by o Several clarifications and corrections, based on the AD review by
Dan Romascanu. Dan Romascanu.
C.2. Changes from 04 to 05 C.3. Changes from 04 to 05
o Changed 'object' terminology to 'data definition'. o Changed 'object' terminology to 'data definition'.
o Put XPath guidelines in separate section. o Put XPath guidelines in separate section.
o Clarified XPath usage for XML document order dependencies. o Clarified XPath usage for XML document order dependencies.
o Updated <CODE BEGINS> guidelines to current conventions. o Updated <CODE BEGINS> guidelines to current conventions.
o Added informative reference for IANA considerations guidelines and o Added informative reference for IANA considerations guidelines and
XML registry. XML registry.
o Updated IANA Considerations section to reserve the ietf-template o Updated IANA Considerations section to reserve the ietf-template
module in the YANG Module Name Registry so it cannot be reused module in the YANG Module Name Registry so it cannot be reused
accidently. accidently.
o Many other clarifications and fixed typos found in WGLC reviews. o Many other clarifications and fixed typos found in WGLC reviews.
C.3. Changes from 03 to 04 C.4. Changes from 03 to 04
o Removed figure 1 to reduce duplication, just refer to 4741bis o Removed figure 1 to reduce duplication, just refer to 4741bis
draft. draft.
o Fixed bugs and typos found in WGLC reviews. o Fixed bugs and typos found in WGLC reviews.
o Removed some guidelines and referring to YANG draft instead of o Removed some guidelines and referring to YANG draft instead of
duplicating YANG rules here. duplicating YANG rules here.
o Changed security guidelines so they refer to the IETF Trust TLP o Changed security guidelines so they refer to the IETF Trust TLP
skipping to change at page 29, line 25 skipping to change at page 29, line 35
o Added guideline that strings should not rely on preservation of o Added guideline that strings should not rely on preservation of
leading and trailing whitespace characters. leading and trailing whitespace characters.
o Relaxed some XPath and anyxml guidelines from SHOULD NOT or MUST o Relaxed some XPath and anyxml guidelines from SHOULD NOT or MUST
NOT to MAY use with caution. NOT to MAY use with caution.
o Updated the TLP text within the example module again. o Updated the TLP text within the example module again.
o Reversed order of change log so most recent entries are first. o Reversed order of change log so most recent entries are first.
C.4. Changes from 02 to 03 C.5. Changes from 02 to 03
o Updated figure 1 to align with 4741bis draft. o Updated figure 1 to align with 4741bis draft.
o Updated guidelines for import-by-revision and include-by-revision. o Updated guidelines for import-by-revision and include-by-revision.
o Added file name to code begins convention in ietf-template module. o Added file name to code begins convention in ietf-template module.
C.5. Changes from 01 to 02 C.6. Changes from 01 to 02
o Updated figure 1 per mailing list comments. o Updated figure 1 per mailing list comments.
o Updated suggested organization to include the working group name. o Updated suggested organization to include the working group name.
o Updated ietf-template.yang to use new organization statement o Updated ietf-template.yang to use new organization statement
value. value.
o Updated Code Component requirements as per new TLP. o Updated Code Component requirements as per new TLP.
o Updated ietf-template.yang to use new Code Component begin and end o Updated ietf-template.yang to use new Code Component begin and end
markers. markers.
o Updated references to the TLP in a couple sections. o Updated references to the TLP in a couple sections.
o Change manager/agent terminology to client/server. o Change manager/agent terminology to client/server.
C.6. Changes from 00 to 01 C.7. Changes from 00 to 01
o Added transport 'TLS' to figure 1. o Added transport 'TLS' to figure 1.
o Added note about RFC 2119 terminology. o Added note about RFC 2119 terminology.
o Corrected URL for instructions to authors. o Corrected URL for instructions to authors.
o Updated namespace procedures section. o Updated namespace procedures section.
o Updated guidelines on module contact, reference, and organization o Updated guidelines on module contact, reference, and organization
 End of changes. 14 change blocks. 
21 lines changed or deleted 35 lines changed or added

This html diff was produced by rfcdiff 1.38. The latest version is available from http://tools.ietf.org/tools/rfcdiff/