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/