draft-ietf-netmod-yang-usage-07.txt   draft-ietf-netmod-yang-usage-08.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 23, 2010 Intended status: Informational July 8, 2010
Expires: December 25, 2010 Expires: January 9, 2011
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-07 draft-ietf-netmod-yang-usage-08
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 25, 2010. This Internet-Draft will expire on January 9, 2011.
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 16 skipping to change at page 2, line 16
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
3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 7 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 7
3.2. Narrative Sections . . . . . . . . . . . . . . . . . . . . 7 3.2. Narrative Sections . . . . . . . . . . . . . . . . . . . . 8
3.3. Definitions Section . . . . . . . . . . . . . . . . . . . 8 3.3. Definitions Section . . . . . . . . . . . . . . . . . . . 8
3.4. Security Considerations 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.1. Documents that Create a New Name Space . . . . . . . . 9
3.5.2. Documents that Extend an Existing Name Space . . . . . 9 3.5.2. Documents that Extend an Existing Name Space . . . . . 9
3.6. Reference Sections . . . . . . . . . . . . . . . . . . . . 9 3.6. Reference Sections . . . . . . . . . . . . . . . . . . . . 10
3.7. Intellectual Property Section . . . . . . . . . . . . . . 9 3.7. Intellectual Property Section . . . . . . . . . . . . . . 10
4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 10 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 11
4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 10 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 11
4.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 10 4.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 11
4.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.4. Conditional Statements . . . . . . . . . . . . . . . . . . 11 4.4. Conditional Statements . . . . . . . . . . . . . . . . . . 12
4.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 11 4.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 12
4.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 12 4.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 13
4.7. Module Header, Meta, and Revision Statements . . . . . . . 13 4.7. Module Header, Meta, and Revision Statements . . . . . . . 14
4.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 14 4.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 15
4.9. Top Level Data Definitions . . . . . . . . . . . . . . . . 15 4.9. Top Level Data Definitions . . . . . . . . . . . . . . . . 16
4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 15 4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 16
4.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 16 4.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 17
4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 16 4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 17
4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 17 4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 18
4.14. Notification Definitions . . . . . . . . . . . . . . . . . 18 4.14. Notification Definitions . . . . . . . . . . . . . . . . . 19
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.1. Normative References . . . . . . . . . . . . . . . . . . . 22 8.1. Normative References . . . . . . . . . . . . . . . . . . . 23
8.2. Informative References . . . . . . . . . . . . . . . . . . 22 8.2. Informative References . . . . . . . . . . . . . . . . . . 23
Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 23 Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 24
Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 25 Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 26
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 28 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 29
C.1. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 28 C.1. Changes from 07 to 08 . . . . . . . . . . . . . . . . . . 29
C.2. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 28 C.2. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 29
C.3. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 28 C.3. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 29
C.4. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 28 C.4. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 29
C.5. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 29 C.5. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 30
C.6. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 29 C.6. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 30
C.7. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 30 C.7. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 31
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 31 C.8. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 31
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 32
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 SMIv2 usage guidelines specification [RFC4181] in similar to the SMIv2 usage guidelines specification [RFC4181] in
skipping to change at page 7, line 41 skipping to change at page 7, line 41
http://trustee.ietf.org/license-info/ http://trustee.ietf.org/license-info/
Each YANG module or submodule contained within an Internet-Draft or Each YANG module or submodule contained within an Internet-Draft or
RFC is considered to be a code component. The strings '<CODE RFC is considered to be a code component. The strings '<CODE
BEGINS>' and '<CODE ENDS>' MUST be used to identify each code BEGINS>' and '<CODE ENDS>' MUST be used to identify each code
component. component.
The '<CODE BEGINS>' tag SHOULD be followed by a string identifying The '<CODE BEGINS>' tag SHOULD be followed by a string identifying
the file name specified in section 5.2 of [I-D.ietf-netmod-yang]. 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 The following example is for the '2010-01-18' revision of the 'ietf-
'2010-01-18', then the following '<CODE BEGINS>' line would be used: foo' module:
<CODE BEGINS> file "ietf-foo@2010-01-18.yang" <CODE BEGINS> file "ietf-foo@2010-01-18.yang"
module ietf-foo {
// ...
revision 2010-01-18 {
description "Latest revision";
reference "RFC XXXXX";
}
// ...
}
<CODE ENDS>
Figure 1
3.2. Narrative Sections 3.2. Narrative Sections
The narrative part MUST include an overview section that describes The narrative part MUST include an overview section that describes
the scope and field of application of the module(s) defined by the the scope and field of application of the module(s) defined by the
specification and that specifies the relationship (if any) of these specification and that specifies the relationship (if any) of these
modules to other standards, particularly to standards containing modules to other standards, particularly to standards containing
other YANG modules. The narrative part SHOULD include one or more other YANG modules. The narrative part SHOULD include one or more
sections to briefly describe the structure of the modules defined in sections to briefly describe the structure of the modules defined in
the specification. the specification.
skipping to change at page 8, line 32 skipping to change at page 9, line 6
these guidelines. 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/netconf/yang-security-considerations.txt).
In particular, writable data nodes that could be especially In particular:
disruptive if abused MUST be explicitly listed by name and the
associated security risks MUST be spelled out; similarly, readable o Writable data nodes that could be especially disruptive if abused
data nodes that contain especially sensitive information or that MUST be explicitly listed by name and the associated security
raise significant privacy concerns MUST be explicitly listed by name risks MUST be explained.
and the reasons for the sensitivity/privacy concerns 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 3.5. IANA Considerations Section
In order to comply with IESG policy as set forth in In order to comply with IESG policy as set forth in
http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is
submitted to the IESG for publication which has action items for IANA submitted to the IESG for publication which has action items for IANA
MUST contain an IANA Considerations section. The requirements for MUST contain an IANA Considerations section. The requirements for
this section vary depending what actions are required of the IANA. this section vary depending what actions are required of the IANA.
If there are no IANA considerations applicable to the document, then If there are no IANA considerations applicable to the document, then
the IANA Considerations section is not required. Refer to the the IANA Considerations section is not required. Refer to the
skipping to change at page 15, line 49 skipping to change at page 16, line 49
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 be 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
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.
The signed numeric data types (i.e., 'int8', 'int16', 'int32', and The signed numeric data types (i.e., 'int8', 'int16', 'int32', and
'int64') SHOULD NOT be used unless negative values are allowed for 'int64') SHOULD NOT be used unless negative values are allowed for
the desired semantics. the desired semantics.
For enumeration or bits data types, the semantics for each enum or For enumeration or bits data types, the semantics for each enum or
bit SHOULD be documented. A separate description statement (within bit SHOULD be documented. A separate description statement (within
skipping to change at page 20, line 12 skipping to change at page 21, line 12
| reference | RFCXXXX | | reference | RFCXXXX |
+---------------+-------------------------------------------+ +---------------+-------------------------------------------+
6. Security Considerations 6. Security Considerations
This document defines documentation guidelines for NETCONF content This document defines documentation guidelines for NETCONF content
defined with the YANG data modeling language. The guidelines for how defined with the YANG data modeling language. The guidelines for how
to write a Security Considerations section for a YANG module are to write a Security Considerations section for a YANG module are
defined in the online document 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 This document does not introduce any new or increased security risks
into the management system. into the management system.
7. Acknowledgments 7. Acknowledgments
The structure and contents of this document are adapted from The structure and contents of this document are adapted from
Guidelines for MIB Documents [RFC4181], by C. M. Heard. Guidelines for MIB Documents [RFC4181], by C. M. Heard.
The working group thanks Martin Bjorklund and Juergen Schoenwaelder The working group thanks Martin Bjorklund and Juergen Schoenwaelder
skipping to change at page 23, line 34 skipping to change at page 24, line 34
3. IETF Trust Copyright -- verify that the draft has the appropriate 3. IETF Trust Copyright -- verify that the draft has the appropriate
text regarding the rights that document contributers provide to text regarding the rights that document contributers provide to
the IETF Trust [RFC5378]. Some guidelines related to this the IETF Trust [RFC5378]. Some guidelines related to this
requirement are described in Section 3.1. The IETF Trust license requirement are described in Section 3.1. The IETF Trust license
policy (TLP) can be found at: policy (TLP) can be found at:
http://trustee.ietf.org/docs/IETF-Trust-License-Policy.pdf http://trustee.ietf.org/docs/IETF-Trust-License-Policy.pdf
4. Security Considerations Section -- verify that the draft uses the 4. Security Considerations Section -- verify that the draft uses the
latest approved template from the OPS area web site latest approved template from the OPS area web site (http://
(http://www.ops.ietf.org/yang-security-considerations.txt) and www.ops.ietf.org/netconf/yang-security-considerations.txt) and
that the guidelines therein have been followed. that the guidelines therein have been followed.
5. IANA Considerations Section -- this section must always be 5. IANA Considerations Section -- this section must always be
present. For each module within the document, ensure that the present. For each module within the document, ensure that the
IANA Considerations section contains entries for the following IANA Considerations section contains entries for the following
IANA registries: IANA registries:
XML Namespace Registry: Register the YANG module namespace. XML Namespace Registry: Register the YANG module namespace.
YANG Module Registry: Register the YANG module name, prefix, YANG Module Registry: Register the YANG module name, prefix,
skipping to change at page 27, line 4 skipping to change at page 28, line 4
// rpc statements // rpc statements
// notification statements // notification statements
// 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 2
Appendix C. Change Log 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 Corrected title change bug; supposed to be page header instead.
o Fixed typos added to last revision. o Fixed typos added to last revision.
o Added sentence to checklist to make sure text outside module o Added sentence to checklist to make sure text outside module
contains citations for imports. 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 o Several clarifications and corrections, based on the AD review by
Dan Romascanu. Dan Romascanu.
C.3. Changes from 04 to 05 C.4. 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.4. Changes from 03 to 04 C.5. 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 35 skipping to change at page 30, line 48
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.5. Changes from 02 to 03 C.6. 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.6. Changes from 01 to 02 C.7. 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.7. Changes from 00 to 01 C.8. 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. 21 change blocks. 
64 lines changed or deleted 92 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/