Network Working Group J. Schönwälder Internet-Draft Constructor University Intended status: Standards Track 24 July 2023 Expires: 25 January 2024 YANG 1.1 with Relaxed Versioning (YANG 1.2) draft-schoenw-netmod-yang-relaxed-versioning-00 Abstract This document relaxes the module update rules of the YANG data modeling language allowing authors to make non-backwards compatible changes in limited situations. The YANG 1.1 specification together with the extensions and updates defined in this document defines YANG version 1.2. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 25 January 2024. Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Schönwälder Expires 25 January 2024 [Page 1] Internet-Draft YANG Relaxed Versioning (YANG 1.2) July 2023 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Import and Include by Minimum Revision . . . . . . . . . . . 3 3. Annotations to Indicate Changes . . . . . . . . . . . . . . . 3 4. Relaxing Module Update Rules . . . . . . . . . . . . . . . . 5 5. YANG ABNF Grammar Extensions . . . . . . . . . . . . . . . . 6 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 6 8. Normative References . . . . . . . . . . . . . . . . . . . . 6 9. Informative References . . . . . . . . . . . . . . . . . . . 6 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction YANG [RFC7950] is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF) [RFC6241]. Section 11 of [RFC7950] defines the rules for updating a YANG module. The update rules were designed to avoid interoperability problems: | [...] changes to published modules are not allowed if they have | any potential to cause interoperability problems between a client | using an original specification and a server using an updated | specification. Section 11 details a number of allowed changes and then concludes with the following general rule: | Otherwise, if the semantics of any previous definition are changed | (i.e., if a non-editorial change is made to any definition other | than those specifically allowed above), then this MUST be achieved | by a new definition with a new identifier. In the real world, there are situations where the cost of introducing a new definition do not align with the risk of making a non-backwards compatible change. The relaxed versioning rules allow limited non- backwards compatible changes if the costs of introducing new definitions significantly outweigh the costs associated with the risk to breaking deployed systems. The following changes to the YANG 1.1 language are made: 1. This document defines an import by minimum revision mechanism, which improves the existing overly restrictive import by exact revision statement. Schönwälder Expires 25 January 2024 [Page 2] Internet-Draft YANG Relaxed Versioning (YANG 1.2) July 2023 2. This document introduces annotations to indicate in which version of a YANG module definitions were added, updated, removed, or semantically changed. 3. This document relaxes the YANG module update rules to allow non- backwards compatible changes in situations where the full implications on deployed clients are understood and the risks have been carefully weighed against the costs of introducing new definitions. An implementation of [RFC7950] also implementing this specification is called YANG 1.2. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2. Import and Include by Minimum Revision The YANG 1.1 import and include statements are extended by allowing a "min-revision-date" substatement defining the minimum revision that an imported or included module must have. import foo-module { min-revision-date 2023-04-01; } DISCUSS: It may make sense to also introduce 'max-revision-date' as this may be necessary eventually. 3. Annotations to Indicate Changes The YANG language is extended with statements that indicate when definitions were added, when definitions where updated, when the status of definitions changed, and when definitions changed in a non- backwards compatible way. Furthermore, the status statement is revised to allow for substatements, namely description statements and statements detailing when additions or changes were made. Here is an example. Lets assume that a leaf 'foo' is added to a module after its first publication: Schönwälder Expires 25 January 2024 [Page 3] Internet-Draft YANG Relaxed Versioning (YANG 1.2) July 2023 leaf foo { type int16; description "A number identifying a foo."; since 2021-12-06; } Note that this is a shorthand notation expanding to the following: leaf foo { type int16; description "A number identifying a foo."; status current { since 2021-12-06; } } The 'since' statement defaults to the initial version of a module if it is not present, hence no 'since' statements are needed for definitions that were part of the initial published version of a module. Lets assume that using a signed integer type was later found to be a mistake. The robust and default path forward is the introduction of a new leaf 'bar' and the deprecation of the old leaf 'foo'. leaf bar { type uint16; description "An unsigned number identifying a foo."; since 2023-04-01; } leaf foo { type int16; description "A number identifying a foo."; since 2021-12-06; status deprecated { since 2023-04-01; description "This leaf uses signed values, which has led to interoperability problems. Implementations should use the new bar leaf instead, which uses an unsigned number space."; } } Schönwälder Expires 25 January 2024 [Page 4] Internet-Draft YANG Relaxed Versioning (YANG 1.2) July 2023 Modules can use the import by minimum revision mechanism to import version 2023-04-01 (or later) and then make use of 'bar' instead of 'foo'. In the special and rare situation where replacing 'foo' with 'bar' is considered too costly relative to the risks of breaking deployed systems, the following non-backwards compatible change can be made leaf foo { type uint16; description "An unsigned number identifying a foo."; status current { since 2021-12-06; changed 2023-04-01 { description "The leaf used signed int16 values, which has led to interoperability problems. This got fixed by changing to an unsigned type. This potentially breaks systems that use negative values. Such systems are considered to be rare if they exist at all."; } } } DISCUSS: More clearly distinguish between backward compatible updates and non-backwards compatible changes. Right now, I am thinking of using 'updated' for backwards compatible changes and 'changed' for non-backwards compatible changes but perhaps this is too subtle? 4. Relaxing Module Update Rules The following statement in Section 11 of RFC 7050 | Otherwise, if the semantics of any previous definition are changed | (i.e., if a non-editorial change is made to any definition other | than those specifically allowed above), then this MUST be achieved | by a new definition with a new identifier. is replaced by the following text: Otherwise, if the semantics of any previous definition are changed (i.e., if a non-editorial change is made to any definition other than those specifically allowed above), then this SHOULD be achieved by a new definition with a new identifier. In exceptional and rare cases, where the costs of introducing a new definition clearly outweighs the risks of potentially breaking deployed implementations, a non- Schönwälder Expires 25 January 2024 [Page 5] Internet-Draft YANG Relaxed Versioning (YANG 1.2) July 2023 backwards compatible change can be made. The appropriate annotation statements MUST be used in this situation to clearly describe the non-backwards compatible change. 5. YANG ABNF Grammar Extensions TODO 6. Security Considerations This document defines an extension of the YANG data modeling language. The definitions themselves have no security impact on the Internet, but the usage of these definitions in concrete YANG modules might have. The security considerations spelled out in the YANG specification [RFC7950] apply for this document as well. 7. Acknowledgments Helpful comments on various versions of this document were provided by the following individuals: TBD 8. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 9. Informative References [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . Author's Address Jürgen Schönwälder Constructor University Email: jschoenwaelder@constructor.university Schönwälder Expires 25 January 2024 [Page 6]