draft-ietf-netmod-yang-usage-02.txt   draft-ietf-netmod-yang-usage-03.txt 
Internet Engineering Task Force A. Bierman Internet Engineering Task Force A. Bierman
Internet-Draft Netconf Central, Inc. Internet-Draft InterWorking Labs
Intended status: Informational October 26, 2009 Intended status: Informational January 15, 2010
Expires: April 29, 2010 Expires: July 19, 2010
Guidelines for Authors and Reviewers of YANG Data Model Documents Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-yang-usage-02 draft-ietf-netmod-yang-usage-03
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.
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 1, line 32 skipping to change at page 1, line 41
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."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on April 29, 2010. This Internet-Draft will expire on July 19, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2009 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 in effect on the date of Provisions Relating to IETF Documents
publication of this document (http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
Abstract include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
This memo provides guidelines for authors and reviewers of standards described in the BSD License.
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.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5
2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5
2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. General Documentation Guidelines . . . . . . . . . . . . . . . 7 3. General Documentation Guidelines . . . . . . . . . . . . . . . 7
skipping to change at page 3, line 49 skipping to change at page 3, line 49
6. Security Considerations . . . . . . . . . . . . . . . . . . . 19 6. Security Considerations . . . . . . . . . . . . . . . . . . . 19
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21
8.1. Normative References . . . . . . . . . . . . . . . . . . . 21 8.1. Normative References . . . . . . . . . . . . . . . . . . . 21
8.2. Informative References . . . . . . . . . . . . . . . . . . 21 8.2. Informative References . . . . . . . . . . . . . . . . . . 21
Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 22 Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 22
Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 24 Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 24
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 27 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 27
C.1. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 27 C.1. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 27
C.2. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 27 C.2. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 27
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 28 C.3. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 27
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 29
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
similar to the MIB usage guidelines specification [RFC4181] in intent similar to the MIB usage guidelines specification [RFC4181] in intent
and structure. and structure.
Many YANG constructs are defined as optional to use, such as the Many YANG constructs are defined as optional to use, such as the
description clause. However, in order to maximize interoperability description clause. However, in order to maximize interoperability
of NETCONF implementations utilizing YANG data models, it is of NETCONF implementations utilizing YANG data models, it is
desirable to define a set of usage guidelines which may require a desirable to define a set of usage guidelines which may require a
higher level of compliance than the minimum level defined in the YANG higher level of compliance than the minimum level defined in the YANG
specification. specification.
The NETCONF stack can be conceptually partitioned into four layers. The NETCONF stack can be conceptually partitioned into four layers.
Layer Example Layer Example
+-------------+ +--------------------+ +-------------------+ +-------------+ +--------------------+ +-------------------+
(4) | Content | | Configuration data | | Notification data | (4) | Content | | Configuration data | | Notification data |
+-------------+ +--------------------+ +-------------------+ +-------------+ +--------------------+ +-------------------+
| | | | | |
+-------------+ +-----------------+ +---------------+ +-------------+ +-----------------+ |
(3) | Operations | | <edit-config> | | <eventType> | (3) | Operations | | <edit-config> | |
+-------------+ +-----------------+ +---------------+ +-------------+ +-----------------+ |
| | | | | |
+-------------+ +--------------------+ +----------------+ +-------------+ +--------------------+ +----------------+
(2) | Messages | | <rpc>, <rpc-reply> | | <notification> | (2) | Messages | | <rpc>, <rpc-reply> | | <notification> |
+-------------+ +--------------------+ +----------------+ +-------------+ +--------------------+ +----------------+
| | | | | |
+-------------+ +-----------------------------------------------+ +-------------+ +-----------------------------------------+
(1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/BEEP, SOAP/HTTPS ... | (1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/HTTP/TLS, ... |
| Transports | | | | Transports | | |
+-------------+ +-----------------------------------------------+ +-------------+ +-----------------------------------------+
Figure 1 Figure 1
This document defines usage guidelines related to the NETCONF This document defines usage guidelines related to the NETCONF
operations layer (3), and NETCONF content layer (4). operations layer (3), and NETCONF content layer (4).
2. Terminology 2. Terminology
2.1. Requirements Notation 2.1. Requirements Notation
skipping to change at page 12, line 26 skipping to change at page 12, line 26
The status statement SHOULD NOT be present if its value is 'current'. The status statement SHOULD NOT be present if its value is 'current'.
It MUST be present if its value is 'deprecated' or 'obsolete'. It MUST be present if its value is 'deprecated' or 'obsolete'.
The module or submodule name MUST NOT be changed, once the document The module or submodule name MUST NOT be changed, once the document
containing the module or submodule is published. containing the module or submodule is published.
The module namespace URI value SHOULD NOT be changed, once the The module namespace URI value SHOULD NOT be changed, once the
document containing the module is published. document containing the module is published.
The revision-date sub-statement (within the imports statement) SHOULD The revision-date sub-statement (within the imports statement) SHOULD
be present. It MUST be present (in all published modules) if any be present if any groupings are used from the external module.
groupings are used from the external module.
The revision-date sub-statement (within the include statement) MAY be The revision-date sub-statement (within the include statement) SHOULD
present. It SHOULD be present (in all published modules) if any be present if any groupings are used from the external sub-module.
groupings are used from the external sub-module.
4.6. Header Contents 4.6. Header Contents
For published modules, the namespace MUST be a globally unique URI, For published modules, the namespace MUST be a globally unique URI,
as defined in [RFC3986]. This value is usually assigned by the IANA. as defined in [RFC3986]. This value is usually assigned by the IANA.
The organization statement MUST be present. If the module is The organization statement MUST be present. If the module is
contained in a documented intended for standards-track status, then contained in a documented intended for standards-track status, then
the organization SHOULD be the IETF working group chartered to write the organization SHOULD be the IETF working group chartered to write
the document. the document.
skipping to change at page 21, line 21 skipping to change at page 21, line 21
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006. December 2006.
[I-D.ietf-netmod-yang] [I-D.ietf-netmod-yang]
Bjorklund, M., "YANG - A data modeling language for Bjorklund, M., "YANG - A data modeling language for
NETCONF", draft-ietf-netmod-yang-08 (work in progress), NETCONF", draft-ietf-netmod-yang-10 (work in progress),
October 2009. January 2010.
[I-D.ietf-netmod-yang-types] [I-D.ietf-netmod-yang-types]
Schoenwaelder, J., "Common YANG Data Types", Schoenwaelder, J., "Common YANG Data Types",
draft-ietf-netmod-yang-types-04 (work in progress), draft-ietf-netmod-yang-types-05 (work in progress),
October 2009. December 2009.
8.2. Informative References 8.2. Informative References
[RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB
Documents", BCP 111, RFC 4181, September 2005. Documents", BCP 111, RFC 4181, September 2005.
Appendix A. Module Review Checklist Appendix A. Module Review Checklist
This section is adapted from RFC 4181. This section is adapted from RFC 4181.
skipping to change at page 24, line 7 skipping to change at page 24, line 7
errors; see [YANG tool URL TBD] for more information. Checking errors; see [YANG tool URL TBD] for more information. Checking
for correct syntax, however, is only part of the job. It is for correct syntax, however, is only part of the job. It is
just as important to actually read the YANG module document from just as important to actually read the YANG module document from
the point of view of a potential implementor. It is 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
implementations to be created. implementations to be created.
Appendix B. YANG Module Template Appendix B. YANG Module Template
<CODE BEGINS> <CODE BEGINS> file "ietf-template.yang"
module ietf-template { module ietf-template {
// replace this string with a unique namespace URN value // replace this string with a unique namespace URN value
namespace namespace
"urn:ietf:params:xml:ns:yang:ietf-template:DRAFT-02"; "urn:ietf:params:xml:ns:yang:ietf-template:DRAFT-02";
// replace this string, and try to pick a unique prefix // replace this string, and try to pick a unique prefix
prefix "temp"; prefix "temp";
skipping to change at page 28, line 5 skipping to change at page 27, line 47
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.3. 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.
Author's Address Author's Address
Andy Bierman Andy Bierman
Netconf Central, Inc. InterWorking Labs
Simi Valley, CA
USA
Email: andy@netconfcentral.com Email: andyb@iwl.com
 End of changes. 16 change blocks. 
51 lines changed or deleted 60 lines changed or added

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