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,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

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,
              <https://www.rfc-editor.org/info/rfc6241>.

Author's Address

   Jürgen Schönwälder
   Constructor University
   Email: jschoenwaelder@constructor.university



Schönwälder              Expires 25 January 2024                [Page 6]