rfc9907v3.txt		rfc9907.txt
	Internet Engineering Task Force (IETF) A. Bierman		Internet Engineering Task Force (IETF) A. Bierman
	Request for Comments: 9907 YumaWorks		Request for Comments: 9907 YumaWorks
	BCP: 216 M. Boucadair, Ed.		BCP: 216 M. Boucadair, Ed.
	Obsoletes: 8407 Orange		Obsoletes: 8407 Orange
	Updates: 8126 Q. Wu		Updates: 8126 Q. Wu
	Category: Best Current Practice Huawei		Category: Best Current Practice Huawei
	ISSN: 2070-1721 January 2026		ISSN: 2070-1721 February 2026
	Guidelines for Authors and Reviewers of Documents Containing YANG Data		Guidelines for Authors and Reviewers of Documents Containing YANG Data
	Models		Models
	Abstract		Abstract
	This document provides guidelines for authors and reviewers of		This document provides guidelines for authors and reviewers of
	specifications containing YANG data models, including IANA-maintained		specifications containing YANG data models, including IANA-maintained
	YANG modules. Recommendations and procedures are defined, which are		YANG modules. Recommendations and procedures are defined, which are
	intended to increase interoperability and usability of Network		intended to increase interoperability and usability of Network
	skipping to change at line 319 ¶		skipping to change at line 319 ¶
	* Added a discussion about "must + error-message" constructs for		* Added a discussion about "must + error-message" constructs for
	state data.		state data.
	* Added text about summary of changes in "revision" statements.		* Added text about summary of changes in "revision" statements.
	* Added a template for IANA-maintained YANG modules.		* Added a template for IANA-maintained YANG modules.
	* Updated the wiki URLs to use the new structure.		* Updated the wiki URLs to use the new structure.
	* Added anydata to the list of statements with mandatory		* Added "anydata" to the list of statements with mandatory
	description(s) (Section 4.14).		description(s) (Section 4.14).
	* Fixed an error (invalid statements) in Section 4.24.		* Fixed an error (invalid statements) in Section 4.24.
	* Softened generic I-D authorship guidance.		* Softened generic I-D authorship guidance.
	2. Terminology and Notation Conventions		2. Terminology and Notation Conventions
	Some of the templates defined in the document use "--" to easily		Some of the templates defined in the document use "--" to easily
	identify specific instructions to the authors. Text prefixed with		identify specific instructions to the authors. Text prefixed with
	skipping to change at line 873 ¶		skipping to change at line 873 ¶
	Additional IANA considerations applicable to IANA-maintained YANG		Additional IANA considerations applicable to IANA-maintained YANG
	modules (including instructions to maintain them) are provided in		modules (including instructions to maintain them) are provided in
	Section 4.30.3.		Section 4.30.3.
	3.8.1. Documents That Create a New Namespace		3.8.1. Documents That Create a New Namespace
	If an I-D defines a new namespace that is to be administered by the		If an I-D defines a new namespace that is to be administered by the
	IANA, then the document MUST include an IANA Considerations section		IANA, then the document MUST include an IANA Considerations section
	that specifies how the namespace is to be administered.		that specifies how the namespace is to be administered.
	Specifically, if any YANG module namespace statement value contained		Specifically, if any YANG module "namespace" statement value
	in the document is not already registered with IANA, then a new entry		contained in the document is not already registered with IANA, then a
	in the "ns" registry within the "IETF XML Registry" registry group		new entry in the "ns" registry within the "IETF XML Registry"
	MUST be requested from the IANA.		registry group MUST be requested from the IANA.
	A registration template for new YANG modules is provided in		A registration template for new YANG modules is provided in
	Section 3.8.3.1.		Section 3.8.3.1.
	3.8.2. Documents That Extend an Existing Namespace		3.8.2. Documents That Extend an Existing Namespace
	It is possible to extend an existing namespace using a YANG submodule		It is possible to extend an existing namespace using a YANG submodule
	that belongs to an existing module already administered by IANA. In		that belongs to an existing module already administered by IANA. In
	this case, the document containing the main module MUST be updated to		this case, the document containing the main module MUST be updated to
	use the latest revision of the submodule.		use the latest revision of the submodule.
	skipping to change at line 1444 ¶		skipping to change at line 1444 ¶
	"description" statement for the grouping.		"description" statement for the grouping.
	4.6.2. Function Library		4.6.2. Function Library
	The "position" and "last" functions SHOULD NOT be used. This applies		The "position" and "last" functions SHOULD NOT be used. This applies
	to implicit use of the "position" function as well (e.g.,		to implicit use of the "position" function as well (e.g.,
	'//chapter[42]'). A server is only required to maintain the relative		'//chapter[42]'). A server is only required to maintain the relative
	XML document order of all instances of a particular user-ordered list		XML document order of all instances of a particular user-ordered list
	or leaf-list. The "position" and "last" functions MAY be used if		or leaf-list. The "position" and "last" functions MAY be used if
	they are evaluated in a context where the context node is a user-		they are evaluated in a context where the context node is a user-
	ordered list or leaf-list.		ordered "list" or "leaf-list".
	The "id" function SHOULD NOT be used. The "ID" attribute is not		The "id" function SHOULD NOT be used. The "ID" attribute is not
	present in YANG documents, so this function has no meaning. The		present in YANG documents, so this function has no meaning. The
	XPath execution environment SHOULD return an empty string for this		XPath execution environment SHOULD return an empty string for this
	function.		function.
	The "namespace-uri" and "name" functions SHOULD NOT be used.		The "namespace-uri" and "name" functions SHOULD NOT be used.
	Expanded names in XPath are different than YANG. A specific		Expanded names in XPath are different than YANG. A specific
	canonical representation of a YANG-expanded name does not exist.		canonical representation of a YANG-expanded name does not exist.
	skipping to change at line 1822 ¶		skipping to change at line 1822 ¶
	* the module to compile correctly instead of generating disruptive		* the module to compile correctly instead of generating disruptive
	fatal errors.		fatal errors.
	* early implementors to use the modules without picking a random		* early implementors to use the modules without picking a random
	value for the XML namespace.		value for the XML namespace.
	* early interoperability testing since independent implementations		* early interoperability testing since independent implementations
	will use the same XML namespace value.		will use the same XML namespace value.
	Until a URI is assigned by the IANA, a proposed namespace URI MUST be		Until a URI is assigned by the IANA, a proposed namespace URI MUST be
	provided for the namespace statement in a YANG module. A value		provided for the "namespace" statement in a YANG module. A value
	SHOULD be selected that is not likely to collide with other YANG		SHOULD be selected that is not likely to collide with other YANG
	namespaces. Standard module names, prefixes, and URI strings already		namespaces. Standard module names, prefixes, and URI strings already
	listed in the "YANG Module Names" registry group MUST NOT be used.		listed in the "YANG Module Names" registry group MUST NOT be used.
	A standard namespace statement value SHOULD have the following form:		A standard "namespace" statement value SHOULD have the following
			form:
	<URN prefix string>:<module-name>		<URN prefix string>:<module-name>
	The following URN prefix string SHOULD be used for published and		The following URN prefix string SHOULD be used for published and
	unpublished YANG modules:		unpublished YANG modules:
	urn:ietf:params:xml:ns:yang		urn:ietf:params:xml:ns:yang
	The following example URNs would be valid namespace statement values		The following example URNs would be valid "namespace" statement
	for Standards Track modules:		values for Standards Track modules:
	urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock		urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock
	urn:ietf:params:xml:ns:yang:ietf-netconf-state		urn:ietf:params:xml:ns:yang:ietf-netconf-state
	urn:ietf:params:xml:ns:yang:ietf-netconf		urn:ietf:params:xml:ns:yang:ietf-netconf
	Note that a different URN prefix string SHOULD be used for modules		Note that a different URN prefix string SHOULD be used for modules
	that are not Standards Track. The string SHOULD be selected		that are not Standards Track. The string SHOULD be selected
	according to the guidelines in Section 5.3 of [RFC7950].		according to the guidelines in Section 5.3 of [RFC7950].
	skipping to change at line 3081 ¶		skipping to change at line 3082 ¶
	}		}
	Authors can use existing standard tags or use new tags defined in the		Authors can use existing standard tags or use new tags defined in the
	model definition, as appropriate. For IETF modules, new tags MUST be		model definition, as appropriate. For IETF modules, new tags MUST be
	assigned in the IANA "IETF YANG Module Tags" registry within the		assigned in the IANA "IETF YANG Module Tags" registry within the
	"YANG Module Tags" registry group [IANA-TAGS].		"YANG Module Tags" registry group [IANA-TAGS].
	4.29. Modeling Abstract Data Structures		4.29. Modeling Abstract Data Structures
	For contexts where YANG is used to model abstract data structures		For contexts where YANG is used to model abstract data structures
	(e.g., protocol messages), the use of the "structure" "extension"		(e.g., protocol messages), the use of the "structure" extension
	statement [RFC8791] is RECOMMENDED compared to the "yang-data"		statement [RFC8791] is RECOMMENDED compared to the "yang-data"
	"extension" statement [RFC8040]. Examples of modules that rely upon		"extension" statement [RFC8040]. Examples of modules that rely upon
	the "structure" "extension" statement from [RFC8791] can be found in		the "structure" extension statement from [RFC8791] can be found in
	[RFC9132] or [RFC9195].		[RFC9132] or [RFC9195].
	Abstract data structures can be augmented using the "augment-		Abstract data structures can be augmented using the "augment-
	structure" statement [RFC8791]. Examples of modules that augment		structure" statement [RFC8791]. Examples of modules that augment
	abstract data structures can be found in [RFC9244] and [RFC9362].		abstract data structures can be found in [RFC9244] and [RFC9362].
	4.30. IANA-Maintained YANG Modules		4.30. IANA-Maintained YANG Modules
	4.30.1. Context		4.30.1. Context
	skipping to change at line 3306 ¶		skipping to change at line 3307 ¶
	unassigned or reserved values must not be present in the IANA-		unassigned or reserved values must not be present in the IANA-
	maintained YANG module.		maintained YANG module.
	* An instruction whether experimental values should be included in		* An instruction whether experimental values should be included in
	the IANA-maintained YANG module. If no instruction is provided,		the IANA-maintained YANG module. If no instruction is provided,
	experimental values MUST NOT be listed in the IANA-maintained YANG		experimental values MUST NOT be listed in the IANA-maintained YANG
	module.		module.
	* An instruction about how to generate the "revision" statement. If		* An instruction about how to generate the "revision" statement. If
	no instruction is provided, default actions provided in		no instruction is provided, default actions provided in
	Section 4.30 will be followed.		Section 5.3 will be followed.
	A template for the IANA Considerations is provided in		A template for the IANA Considerations is provided in
	Section 4.30.3.1 for IANA-maintained YANG modules with identities and		Section 4.30.3.1 for IANA-maintained YANG modules with identities and
	Section 4.30.3.2 for IANA-maintained YANG modules with enumerations.		Section 4.30.3.2 for IANA-maintained YANG modules with enumerations.
	Authors may modify the template to reflect specifics of their modules		Authors may modify the template to reflect specifics of their modules
	(e.g., multiple registries can be listed for a single IANA-maintained		(e.g., multiple registries can be listed for a single IANA-maintained
	YANG module, no explicit description (or name) field is listed under		YANG module, no explicit description (or name) field is listed under
	the authoritative IANA registry, or the name does not comply with		the authoritative IANA registry, or the name does not comply with
	YANG naming conventions (Section 4.3.1)).		YANG naming conventions (Section 4.3.1)).
	skipping to change at line 3642 ¶		skipping to change at line 3643 ¶
	applicable to all IANA-maintained YANG modules and instructions that		applicable to all IANA-maintained YANG modules and instructions that
	can be customized by module creators.		can be customized by module creators.
	5.3.1. Requirements for All Modules		5.3.1. Requirements for All Modules
	In particular, the following instructions should apply to all		In particular, the following instructions should apply to all
	modules:		modules:
	* When an underlying registration is deprecated or obsoleted, a		* When an underlying registration is deprecated or obsoleted, a
	corresponding "status" substatement should be added to the		corresponding "status" substatement should be added to the
	identity or enumeration statement.		"identity" or "enum" statement.
	* The "reference" substatement in the "revision" statement should		* The "reference" substatement in the "revision" statement should
	point specifically to the published module (i.e.,		point specifically to the published module (i.e.,
	IANA_FOO_URL_With_REV). When the registration is triggered by an		IANA_FOO_URL_With_REV). When the registration is triggered by an
	RFC, that RFC must also be included in the "reference"		RFC, that RFC must also be included in the "reference"
	substatement. It may also point to an authoritative event		substatement. It may also point to an authoritative event
	triggering the update to the YANG module. In all cases, the event		triggering the update to the YANG module. In all cases, the event
	is cited from the underlying IANA registry.		is cited from the underlying IANA registry.
	* References to documents should include titles.		* References to documents should include titles.
	skipping to change at line 3674 ¶		skipping to change at line 3675 ¶
	5.3.2. Requirements Subject to Customization		5.3.2. Requirements Subject to Customization
	Unless the creators of an IANA-maintained YANG module specify		Unless the creators of an IANA-maintained YANG module specify
	otherwise in their document's IANA Considerations section, the		otherwise in their document's IANA Considerations section, the
	following instructions will apply:		following instructions will apply:
	* Unassigned and reserved values (including experimental values)		* Unassigned and reserved values (including experimental values)
	will be omitted from the module.		will be omitted from the module.
	* The "reference" statement in an "identity" or "enum" substatement		* The "reference" substatement in an "identity" or "enum" statement
	should mirror the underlying registry. It may point to contact		should mirror the underlying registry. It may point to contact
	names as well as documents.		names as well as documents.
	* In a "revision" statement, the "description" substatement captures		* In a "revision" statement, the "description" substatement captures
	what changed in the revised version. Typically, the "description"		what changed in the revised version. Typically, the "description"
	enumerates changes such as updates to existing entries (e.g.,		enumerates changes such as updates to existing entries (e.g.,
	update a "description" or a "reference") or notes which identities		update a "description" or a "reference") or notes which identities
	were added or had their status changed (e.g., deprecated,		were added or had their status changed (e.g., deprecated,
	discouraged, or obsoleted).		discouraged, or obsoleted).
	When such a description is not feasible, the description varies in		When such a description is not feasible, the description varies in
	accordance with the trigger for the update.		accordance with the trigger for the update.
	If the update is triggered by an RFC, the "description" substatement		If the update is triggered by an RFC, the "description" substatement
	should include or consist of this text:		should include or consist of this text:
	"Applied updates as specified by RFC XXXX."		Applied updates as specified by RFC XXXX.
	If the registration policy for the registry does not require RFC		If the registration policy for the registry does not require RFC
	publication (Section 4 of [RFC8126]), insert this text:		publication (Section 4 of [RFC8126]), insert this text:
	"Applied updates as specified by the registration policy		Applied updates as specified by the registration policy
	<Some_IANA_policy>".		<Some_IANA_policy>.
	6. Operational Considerations		6. Operational Considerations
	Although the document focuses on YANG data modeling language		Although the document focuses on YANG data modeling language
	guidance, the document does not define a protocol or a protocol		guidance, the document does not define a protocol or a protocol
	extension. As such, there are no new operations or manageability		extension. As such, there are no new operations or manageability
	requirements introduced by this document.		requirements introduced by this document.
	7. Security Considerations		7. Security Considerations
End of changes. 14 change blocks.
	19 lines changed or deleted		20 lines changed or added
This html diff was produced by rfcdiff 1.48.