< draft-boucadair-netmod-iana-registries-01.txt		draft-boucadair-netmod-iana-registries-02.txt >
	netmod M. Boucadair		netmod M. Boucadair
	Internet-Draft Orange		Internet-Draft Orange
	Updates: 8407 (if approved) 24 March 2022		Updates: 8407 (if approved) 25 March 2022
	Intended status: Standards Track		Intended status: Standards Track
	Expires: 25 September 2022		Expires: 26 September 2022
	Recommendations for Creating IANA-Maintained YANG Modules		Recommendations for Creating IANA-Maintained YANG Modules
	draft-boucadair-netmod-iana-registries-01		draft-boucadair-netmod-iana-registries-02
	Abstract		Abstract
	This document provides a set of guidelines for YANG module authors		This document provides a set of guidelines for YANG module authors
	related to the design of IANA-maintained modules. These guidelines		related to the design of IANA-maintained modules. These guidelines
	are meant to leverage existing IANA registries and use YANG as just		are meant to leverage existing IANA registries and use YANG as just
	another format to present the content of these registries.		another format to present the content of these registries.
	This document updates RFC 8407 by providing additional guidelines for		This document updates RFC 8407 by providing additional guidelines for
	IANA-maintained modules. It also relaxes a recommendation related to		IANA-maintained modules. It does not change anything written in RFC
	the extensibility for such modules.		8407.
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted 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). 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 https://datatracker.ietf.org/drafts/current/.		Drafts is at https://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 25 September 2022.		This Internet-Draft will expire on 26 September 2022.
	Copyright Notice		Copyright Notice
	Copyright (c) 2022 IETF Trust and the persons identified as the		Copyright (c) 2022 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 (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	skipping to change at page 2, line 18 ¶		skipping to change at page 2, line 18 ¶
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
	3. Guidelines for IANA-Maintained Registries . . . . . . . . . . 3		3. Guidelines for IANA-Maintained Registries . . . . . . . . . . 3
	4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4		4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 4		5. Security Considerations . . . . . . . . . . . . . . . . . . . 4
	6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 4		6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 4
	7. References . . . . . . . . . . . . . . . . . . . . . . . . . 4		7. References . . . . . . . . . . . . . . . . . . . . . . . . . 4
	7.1. Normative References . . . . . . . . . . . . . . . . . . 4		7.1. Normative References . . . . . . . . . . . . . . . . . . 4
	7.2. Informative References . . . . . . . . . . . . . . . . . 4		7.2. Informative References . . . . . . . . . . . . . . . . . 5
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
	1. Introduction		1. Introduction
	IANA maintains a set of registries that are key for interoperability.		IANA maintains a set of registries that are key for interoperability.
	The content of these registries are usually available using various		The content of these registries are usually available using various
	formats (e.g., plain text, XML). However, there were some confusion		formats (e.g., plain text, XML). However, there were some confusion
	in the past about whether the content of some registries is dependent		in the past about whether the content of some registries is dependent
	on a specific representation format. For example, Section 5 of		on a specific representation format. For example, Section 5 of
	[RFC8892] was published to clarify that MIB and YANG modules are		[RFC8892] was published to clarify that MIB and YANG modules are
	merely additional formats in which the "Interface Types (ifType)" and		merely additional formats in which the "Interface Types (ifType)" and
	skipping to change at page 3, line 21 ¶		skipping to change at page 3, line 21 ¶
	capitals, as shown here.		capitals, as shown here.
	This document makes use of the terms defined in Section 2 of		This document makes use of the terms defined in Section 2 of
	[RFC8407].		[RFC8407].
	3. Guidelines for IANA-Maintained Registries		3. Guidelines for IANA-Maintained Registries
	When designing a YANG module for a functionality governed by a		When designing a YANG module for a functionality governed by a
	protocol for which IANA maintains a registry, it is RECOMMENDED to		protocol for which IANA maintains a registry, it is RECOMMENDED to
	specify an IANA-maintained module that echoes the content of that		specify an IANA-maintained module that echoes the content of that
	registry.		registry. This is superior to including that content in an IETF-
			maintained module.
	When one or multiple sub-registries are available under the same		When one or multiple sub-registries are available under the same
	registry, it is RECOMMENDED to define an IANA-maintained module for		registry, it is RECOMMENDED to define an IANA-maintained module for
	each sub-registry. However, designers MAY consider defining one		each sub-registry. However, module designers MAY consider defining
	single IANA-maintained module that covers all sub-registries if		one single IANA-maintained module that covers all sub-registries if
	maintaining that single module is manageable (e.g., very few values		maintaining that single module is manageable (e.g., very few values
	are present or expected to be present for each sub-registry).		are present or expected to be present for each sub-registry). An
			example of such a module is documented in Section 5.2 of [RFC9132].
	An IANA-maintained module may use identities (e.g., [RFC8675]) or		An IANA-maintained module MAY use identities (e.g., [RFC8675]) or
	typedefs (e.g., [RFC9108]). Such a decision is left to the module		enumerations (e.g., [RFC9108]). The final decision is left to the
	designers and should be made based upon specifics related to the		module designers and should be made based upon specifics related to
	intended use of the module. It is RECOMMENDED that the reasoning for		the intended use of the module. It is worth mentioning that
	the design choice is documented in the companion specification		identities are useful if the registry entries are organized
	document that registers the module. For example,		hierarchically, possibly including multiple inheritances. It is
	[I-D.ietf-dots-telemetry] defines an IANA-maintained module that uses		RECOMMENDED that the reasoning for the design choice is documented in
	typedefs for the following reason:		the companion specification document that registers the module. For
			example, [I-D.ietf-dots-telemetry] defines an IANA-maintained module
			that uses enumerations for the following reason:
	"The DOTS telemetry module (Section 10.1) uses "enumerations" rather		"The DOTS telemetry module (Section 10.1) uses "enumerations" rather
	than "identities" to define units, samples, and intervals because		than "identities" to define units, samples, and intervals because
	otherwise the namespace identifier "ietf-dots-telemetry" must be		otherwise the namespace identifier "ietf-dots-telemetry" must be
	included when a telemetry attribute is included (e.g., in a		included when a telemetry attribute is included (e.g., in a
	mitigation efficacy update). The use of "identities" is thus		mitigation efficacy update). The use of "identities" is thus
	suboptimal from a message compactness standpoint; one of the key		suboptimal from a message compactness standpoint; one of the key
	requirements for DOTS messages."		requirements for DOTS messages."
	For IANA-maintained modules, this recommendation takes precedence
	over the behavior specified in Section 4.11.1 of [RFC8407] because
	the extensibility concern is not applicable for such modules.
	Designers of IANA-maintained modules MAY supply the full Initial		Designers of IANA-maintained modules MAY supply the full Initial
	version of the module in a specification document that registers the		version of the module in a specification document that registers the
	module or only a script to be used by IANA for generating the module		module or only a script to be used (including by IANA) for generating
	(e.g., an XSLT 1.0 stylesheet in Appendix A of [RFC9108]).		the module (e.g., an XSLT stylesheet as in Appendix A of [RFC9108]).
			When a script is used, the Internet-Draft that defines an IANA-
			maintained module SHOULD include an appendix with the initial full
			version of the module. Including such an appendix in pre-RFC
			versions is meant to assess the correctness of the outcome of the
			supplied script. The authors MUST include a note to the RFC Editor
			requesting that the appendix be removed before publication as RFC.
			Initial versions of IANA-maintained modules that are published in
			RFCs may be misused despite the appropriate language to refer to the
			IANA registry to retrieve the up-to-date module. This is problematic
			for interoperability (e.g., when values are deprecated or are
			associated with a new meaning).
			Note: [Style] provides XSLT 1.0 stylesheets and other tools for
			translating IANA registries to YANG modules. The tools can be
			used to generate up-to-date revisions of an IANA-maintained module
			based upon the XML representation of an IANA registry.
	4. IANA Considerations		4. IANA Considerations
	This document does not require any IANA action.		This document does not require any IANA action.
	5. Security Considerations		5. Security Considerations
	This document does not introduce new concerns other than those		This document does not introduce new concerns other than those
	already discussed in Section 15 of [RFC8407].		already discussed in Section 15 of [RFC8407].
	6. Acknowledgements		6. Acknowledgements
	This document is triggered by a discussion the author had with Dhruv		This document is triggered by a discussion the author had with Dhruv
	Dhody and Jensen Zhang.		Dhody and Jensen Zhang.
	Thanks to Juergen Schoenwaelder for the comments.		Thanks to Juergen Schoenwaelder and Ladislav Lhotka for the
			discussion and valuable comments. Special thanks to Ladislav Lhotka
			for sharing more context that led to the design documented in
			[RFC9108].
	7. References		7. References
	7.1. Normative References		7.1. Normative References
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://www.rfc-editor.org/info/rfc2119>.
	skipping to change at page 5, line 33 ¶		skipping to change at page 6, line 5 ¶
	[RFC9108] Lhotka, L. and P. Špaček, "YANG Types for DNS Classes and		[RFC9108] Lhotka, L. and P. Špaček, "YANG Types for DNS Classes and
	Resource Record Types", RFC 9108, DOI 10.17487/RFC9108,		Resource Record Types", RFC 9108, DOI 10.17487/RFC9108,
	September 2021, <https://www.rfc-editor.org/info/rfc9108>.		September 2021, <https://www.rfc-editor.org/info/rfc9108>.
	[RFC9132] Boucadair, M., Ed., Shallow, J., and T. Reddy.K,		[RFC9132] Boucadair, M., Ed., Shallow, J., and T. Reddy.K,
	"Distributed Denial-of-Service Open Threat Signaling		"Distributed Denial-of-Service Open Threat Signaling
	(DOTS) Signal Channel Specification", RFC 9132,		(DOTS) Signal Channel Specification", RFC 9132,
	DOI 10.17487/RFC9132, September 2021,		DOI 10.17487/RFC9132, September 2021,
	<https://www.rfc-editor.org/info/rfc9132>.		<https://www.rfc-editor.org/info/rfc9132>.
			[Style] IANA YANG, "IANA YANG",
			<https://github.com/llhotka/iana-yang>.
	Author's Address		Author's Address
	Mohamed Boucadair		Mohamed Boucadair
	Orange		Orange
	35000 Rennes		35000 Rennes
	France		France
	Email: mohamed.boucadair@orange.com		Email: mohamed.boucadair@orange.com
End of changes. 14 change blocks.
	27 lines changed or deleted		49 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/