diff --git a/yang-module-versioning/draft-ietf-netmod-yang-module-versioning.txt b/yang-module-versioning/draft-ietf-netmod-yang-module-versioning.txt index 1a8885f..cfac721 100644 --- a/yang-module-versioning/draft-ietf-netmod-yang-module-versioning.txt +++ b/yang-module-versioning/draft-ietf-netmod-yang-module-versioning.txt @@ -6,17 +6,17 @@ Network Working Group R. Wilton, Ed. Internet-Draft Cisco Systems, Inc. Updates: 6020, 7950, 8407, 8525 (if approved) R. Rahman, Ed. Intended status: Standards Track -Expires: 9 June 2023 B. Lengyel, Ed. +Expires: 18 May 2024 B. Lengyel, Ed. Ericsson J. Clarke Cisco Systems, Inc. J. Sterne Nokia - 6 December 2022 + 15 November 2023 Updated YANG Module Revision Handling - draft-ietf-netmod-yang-module-versioning-08 + draft-ietf-netmod-yang-module-versioning-11 Abstract @@ -45,7 +45,7 @@ Status of This Memo 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 9 June 2023. + This Internet-Draft will expire on 18 May 2024. @@ -53,14 +53,14 @@ Status of This Memo -Wilton, et al. Expires 9 June 2023 [Page 1] +Wilton, et al. Expires 18 May 2024 [Page 1] -Internet-Draft Updated YANG Module Revision Handling December 2022 +Internet-Draft Updated YANG Module Revision Handling November 2023 Copyright Notice - Copyright (c) 2022 IETF Trust and the persons identified as the + 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 @@ -76,61 +76,55 @@ Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4 - 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 5 + 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 3. Refinements to YANG revision handling . . . . . . . . . . . . 5 3.1. Updating a YANG module with a new revision . . . . . . . 6 - 3.1.1. Backwards-compatible rules . . . . . . . . . . . . . 7 - 3.1.2. Non-backwards-compatible changes . . . . . . . . . . 8 - 3.2. non-backwards-compatible extension statement . . . . . . 8 + 3.1.1. Backwards-compatible rules . . . . . . . . . . . . . 6 + 3.1.2. Non-backwards-compatible changes . . . . . . . . . . 7 + 3.2. non-backwards-compatible extension statement . . . . . . 7 3.3. Removing revisions from the revision history . . . . . . 8 - 3.4. Revision label . . . . . . . . . . . . . . . . . . . . . 10 - 3.4.1. File names . . . . . . . . . . . . . . . . . . . . . 10 - 3.4.2. Revision label scheme extension statement . . . . . . 11 - 3.5. Examples for updating the YANG module revision history . 11 - 4. Guidance for revision selection on imports . . . . . . . . . 14 - 4.1. Recommending a minimum revision for module imports . . . 15 - 4.1.1. Module import examples . . . . . . . . . . . . . . . 16 - 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 17 - 5.1. Resolving ambiguous module imports . . . . . . . . . . . 18 - 5.2. YANG library versioning augmentations . . . . . . . . . . 18 - 5.2.1. Advertising revision-label . . . . . . . . . . . . . 19 - 5.2.2. Reporting how deprecated and obsolete nodes are - handled . . . . . . . . . . . . . . . . . . . . . . . 19 - 6. Versioning of YANG instance data . . . . . . . . . . . . . . 19 - 7. Guidelines for using the YANG module update rules . . . . . . 20 - 7.1. Guidelines for YANG module authors . . . . . . . . . . . 20 - 7.1.1. Making non-backwards-compatible changes to a YANG - module . . . . . . . . . . . . . . . . . . . . . . . 21 - 7.2. Versioning Considerations for Clients . . . . . . . . . . 22 - 8. Module Versioning Extension YANG Modules . . . . . . . . . . 22 - 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 32 - 10. Security considerations . . . . . . . . . . . . . . . . . . . 33 - 10.1. Security considerations for module revisions . . . . . . 33 - - - -Wilton, et al. Expires 9 June 2023 [Page 2] + 3.4. Examples for updating the YANG module revision history . 10 + 4. Guidance for revision selection on imports . . . . . . . . . 12 + 4.1. Recommending a minimum revision for module imports . . . 13 + 4.1.1. Module import examples . . . . . . . . . . . . . . . 14 + 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 15 + 5.1. YANG library versioning augmentations . . . . . . . . . . 15 + 5.1.1. Reporting how deprecated and obsolete nodes are + handled . . . . . . . . . . . . . . . . . . . . . . . 16 + 6. Guidelines for using the YANG module update rules . . . . . . 16 + 6.1. Guidelines for YANG module authors . . . . . . . . . . . 16 + 6.1.1. Making non-backwards-compatible changes to a YANG + module . . . . . . . . . . . . . . . . . . . . . . . 17 + 6.2. Versioning Considerations for Clients . . . . . . . . . . 18 + 7. Module Versioning Extension YANG Modules . . . . . . . . . . 19 + 8. Security considerations . . . . . . . . . . . . . . . . . . . 24 + 8.1. Security considerations for module revisions . . . . . . 24 + 8.2. Security considerations for the modules defined in this + document . . . . . . . . . . . . . . . . . . . . . . . . 25 + 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 + 9.1. YANG Module Registrations . . . . . . . . . . . . . . . . 26 + 9.2. Guidance for versioning in IANA maintained YANG + modules . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 + + + +Wilton, et al. Expires 18 May 2024 [Page 2] -Internet-Draft Updated YANG Module Revision Handling December 2022 - - - 10.2. Security considerations for the modules defined in this - document . . . . . . . . . . . . . . . . . . . . . . . . 34 - 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 - 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 34 - 11.2. Guidance for versioning in IANA maintained YANG - modules . . . . . . . . . . . . . . . . . . . . . . . . 35 - 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 - 12.1. Normative References . . . . . . . . . . . . . . . . . . 36 - 12.2. Informative References . . . . . . . . . . . . . . . . . 38 - Appendix A. Examples of changes that are NBC . . . . . . . . . . 39 - Appendix B. Examples of applying the NBC change guidelines . . . 40 - B.1. Removing a data node . . . . . . . . . . . . . . . . . . 40 - B.2. Changing the type of a leaf node . . . . . . . . . . . . 40 - B.3. Reducing the range of a leaf node . . . . . . . . . . . . 41 - B.4. Changing the key of a list . . . . . . . . . . . . . . . 41 - B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 42 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 +Internet-Draft Updated YANG Module Revision Handling November 2023 + + + 10.1. Normative References . . . . . . . . . . . . . . . . . . 28 + 10.2. Informative References . . . . . . . . . . . . . . . . . 29 + Appendix A. Examples of changes that are NBC . . . . . . . . . . 31 + Appendix B. Examples of applying the NBC change guidelines . . . 31 + B.1. Removing a data node . . . . . . . . . . . . . . . . . . 32 + B.2. Changing the type of a leaf node . . . . . . . . . . . . 32 + B.3. Reducing the range of a leaf node . . . . . . . . . . . . 33 + B.4. Changing the key of a list . . . . . . . . . . . . . . . 33 + B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 34 + Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 34 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 1. Introduction @@ -162,36 +156,30 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 interacting with a server from the available schema that are supported and advertised by the server. These other documents are mentioned here as informative references. Support of the other + documents is not required in an implementation in order to take + advantage of the mechanisms and functionality offered by this module + versioning document. + The document comprises four parts: -Wilton, et al. Expires 9 June 2023 [Page 3] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - documents is not required in an implementation in order to take - advantage of the mechanisms and functionality offered by this module - versioning document. +Wilton, et al. Expires 18 May 2024 [Page 3] + +Internet-Draft Updated YANG Module Revision Handling November 2023 - The document comprises five parts: * Refinements to the YANG 1.1 module revision update procedure, supported by new extension statements to indicate when a revision - contains non-backwards-compatible changes, and an optional - revision label. + contains non-backwards-compatible changes. * Updated guidance for revision selection on imports and a YANG extension statement allowing YANG module imports to document an earliest module revision that may satisfy the import dependency. - * Updates and augmentations to ietf-yang-library to include the - revision label in the module and submodule descriptions, to report - how "deprecated" and "obsolete" nodes are handled by a server, and - to clarify how module imports are resolved when multiple revisions - could otherwise be chosen. - - * Considerations of how versioning applies to YANG instance data. + * Updates and augmentations to ietf-yang-library to report how + "deprecated" and "obsolete" nodes are handled by a server. * Guidelines for how the YANG module update rules defined in this document should be used, along with examples. @@ -208,32 +196,13 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 update rules, and Section 4.1 describes a YANG extension statement to describe potential YANG import revision dependencies. - This document updates [RFC7950] section 5.2, [RFC6020] section 5.2 - and [RFC8407] section 3.2. Section 3.4.1 describes the use of a - revision label in the name of a file containing a YANG module or - submodule. - - This document updates [RFC7950] section 5.6.5 and [RFC8525]. - Section 5.1 defines how a client of a YANG library datastore schema - resolves ambiguous imports for modules which are not "import-only". - - - - - -Wilton, et al. Expires 9 June 2023 [Page 4] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - - This document updates [RFC8407] section 4.7. Section 7 provides + This document updates [RFC8407] section 4.7. Section 6 provides guidelines on managing the lifecycle of YANG modules that may contain non-backwards-compatible changes and a branched revision history. - This document updates [RFC8525] with augmentations to include - revision labels in the YANG library data and two boolean leafs to - indicate whether status deprecated and status obsolete schema nodes - are implemented by the server. + This document updates [RFC8525] with augmentations to include two + boolean leafs to indicate whether status deprecated and status + obsolete schema nodes are implemented by the server. 2. Terminology and Conventions @@ -250,6 +219,13 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 In addition, this document uses the following terminology: + + +Wilton, et al. Expires 18 May 2024 [Page 4] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + * YANG module revision: An instance of a YANG module, uniquely identified with a revision date, with no implied ordering or backwards compatibility between different revisions of the same @@ -274,14 +250,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 non-linear development of YANG module and submodule revisions, so that they MAY have multiple revisions that directly derive from the same parent revision. As per [RFC7950] and [RFC6020], YANG module - - - -Wilton, et al. Expires 9 June 2023 [Page 5] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - and submodule revisions continue to be uniquely identified by their revision date, and hence all revisions of a given module or submodule MUST have unique revision dates. @@ -306,6 +274,14 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 is uniquely defined, the module's "include" statements SHOULD use "revision-date" substatements to specify the exact revision date of each included submodule. When a module does not include its + + + +Wilton, et al. Expires 18 May 2024 [Page 5] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + submodules by revision-date, the revision of submodules used cannot be derived from the including module. Mechanisms such as YANG packages [I-D.ietf-netmod-yang-packages], and YANG library [RFC8525], @@ -331,13 +307,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 refine the rules for permissible changes when a new YANG module revision is created. - - -Wilton, et al. Expires 9 June 2023 [Page 6] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - A new module revision MAY contain NBC changes, e.g., the semantics of an existing data-node definition MAY be changed in an NBC manner without requiring a new data-node definition with a new identifier. @@ -348,10 +317,7 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 recommended to avoid making them. As per [RFC7950] and [RFC6020], all published revisions of a module - are given a new unique revision date. This applies even for module - revisions containing (in the module or included submodules) only - changes to any whitespace, formatting, comments or line endings - (e.g., DOS vs UNIX). + are given a new unique revision date. 3.1.1. Backwards-compatible rules @@ -364,6 +330,14 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 "current" to "deprecated", but adding or changing "status" to "obsolete" is a non-backwards-compatible change. + + + +Wilton, et al. Expires 18 May 2024 [Page 6] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + * YANG schema nodes with a "status" "obsolete" substatement MAY be removed from published modules, and the removal is classified as a backwards-compatible change. In some circumstances it may be @@ -385,15 +359,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 substatetements, or removing any "revision-date" or "recommended- min" substatements, is classified as backwards-compatible. - - - - -Wilton, et al. Expires 9 June 2023 [Page 7] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - * Any changes (including whitespace or formatting changes) that do not change the semantic meaning of the module are backwards- compatible. @@ -418,6 +383,17 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Adding, modifying or removing a "rev:non-backwards-compatible" extension statement is considered to be a BC change. + + + + + + +Wilton, et al. Expires 18 May 2024 [Page 7] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + 3.3. Removing revisions from the revision history Authors may wish to remove revision statements from a module or @@ -442,18 +418,37 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 accurately reflect the compatibility relationship to their preceding entries remaining in the revision history. + The author MUST NOT remove the first (i.e., newest) revision entry in + the revision history. + + Example revision history: + + + + + + + + -Wilton, et al. Expires 9 June 2023 [Page 8] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - The author MUST NOT remove the first (i.e., newest) revision entry in - the revision history. - Example revision history: + + + + + + + + + +Wilton, et al. Expires 18 May 2024 [Page 8] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + revision 2020-11-11 { rev:label 4.0.0; @@ -501,97 +496,17 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 -Wilton, et al. Expires 9 June 2023 [Page 9] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - -3.4. Revision label - - Each revision entry in a module or submodule MAY have a revision - label associated with it, providing an alternative alias to identify - a particular revision of a module or submodule. The revision label - could be used to provide an additional versioning identifier - associated with the revision. - - A revision label scheme is a set of rules describing how a particular - type of revision label operates for versioning YANG modules and - submodules. For example, YANG Semver [I-D.ietf-netmod-yang-semver] - defines a revision label scheme based on Semver 2.0.0 [semver]. - Other documents may define other YANG revision label schemes. - Submodules MAY use a revision label scheme. When they use a revision - label scheme, submodules MAY use a revision label scheme that is - different from the one used in the including module. - The revision label space of submodules is separate from the revision - label space of the including module. A change in one submodule MUST - result in a new revision label of that submodule and the including - module, but the actual values of the revision labels in the module - and submodule could be completely different. A change in one - submodule does not result in a new revision label in another - submodule. A change in a module revision label does not necessarily - mean a change to the revision label in all included submodules. - If a revision has an associated revision label, then it may be used - instead of the revision date in a "rev:recommended-min" extension - statement argument. - A specific revision label identifies a specific revision of the - module. If two YANG modules contain the same module name and the - same revision label (and hence also the same revision-date) in their - latest revision statement, then the file contents of the two modules, - including the revision history, MUST be identical. -3.4.1. File names - - This section updates [RFC7950] section 5.2, [RFC6020] section 5.2 and - [RFC8407] section 3.2 - - If a revision has an associated revision label, then it is - RECOMMENDED that the name of the file for that revision be of the - form: - - - - - - -Wilton, et al. Expires 9 June 2023 [Page 10] +Wilton, et al. Expires 18 May 2024 [Page 9] -Internet-Draft Updated YANG Module Revision Handling December 2022 - - - module-or-submodule-name ['#' revision-label] ( '.yang' / '.yin' ) - - E.g., acme-router-module#2.0.3.yang - - - YANG module (or submodule) files may be identified using either the - revision-date (as per [RFC8407] section 3.2) or the revision label. - -3.4.2. Revision label scheme extension statement - - The optional "rev:revision-label-scheme" extension statement is used - to indicate which revision label scheme a module or submodule uses. - There MUST NOT be more than one revision label scheme in a module or - submodule. The mandatory argument to this extension statement: - - * specifies the revision label scheme used by the module or - submodule - - * is defined in the document which specifies the revision label - scheme +Internet-Draft Updated YANG Module Revision Handling November 2023 - * MUST be an identity derived from "revision-label-scheme-base". - The revision label scheme used by a module or submodule SHOULD NOT - change during the lifetime of the module or submodule. If the - revision label scheme used by a module or submodule is changed to a - new scheme, then all revision label statements that do not conform to - the new scheme MUST be replaced or removed. - -3.5. Examples for updating the YANG module revision history +3.4. Examples for updating the YANG module revision history The following diagram, explanation, and module history illustrates how the branched revision history, "non-backwards-compatible" @@ -600,24 +515,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Example YANG module with branched revision history. - - - - - - - - - - - - - -Wilton, et al. Expires 9 June 2023 [Page 11] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - Module revision date Revision label 2019-01-01 <- 1.0.0 | @@ -660,18 +557,9 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 - - - - - - - - - -Wilton, et al. Expires 9 June 2023 [Page 12] +Wilton, et al. Expires 18 May 2024 [Page 10] -Internet-Draft Updated YANG Module Revision Handling December 2022 +Internet-Draft Updated YANG Module Revision Handling November 2023 module example-module { @@ -725,9 +613,9 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 -Wilton, et al. Expires 9 June 2023 [Page 13] +Wilton, et al. Expires 18 May 2024 [Page 11] -Internet-Draft Updated YANG Module Revision Handling December 2022 +Internet-Draft Updated YANG Module Revision Handling November 2023 module example-module { @@ -773,7 +661,7 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 date. In practice, importing a module with an exact revision date can be too restrictive because it requires the importing module to be updated whenever any change to the imported module occurs, and hence - section Section 7.1 suggests that authors do not restrict YANG module + section Section 6.1 suggests that authors do not restrict YANG module imports to exact revision dates. @@ -781,9 +669,9 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 -Wilton, et al. Expires 9 June 2023 [Page 14] +Wilton, et al. Expires 18 May 2024 [Page 12] -Internet-Draft Updated YANG Module Revision Handling December 2022 +Internet-Draft Updated YANG Module Revision Handling November 2023 Instead, for conformance purposes (section 5.6 of [RFC7950]), the @@ -837,9 +725,9 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 -Wilton, et al. Expires 9 June 2023 [Page 15] +Wilton, et al. Expires 18 May 2024 [Page 13] -Internet-Draft Updated YANG Module Revision Handling December 2022 +Internet-Draft Updated YANG Module Revision Handling November 2023 A particular revision of an imported module adheres to an import's @@ -849,7 +737,7 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 revision history may cause a particular revision to no longer satisfy an import's "recommended-min" statement if the revision- date or label is no longer present in the module's revision - history; further described in Section 3.3 and Section 7.1. + history; further described in Section 3.3 and Section 6.1. The "recommended-min" extension statement MAY be specified multiple times, allowing a set of recommended minimum revisions to @@ -862,7 +750,7 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 4.1.1. Module import examples - Consider the example module "example-module" from Section 3.5 that is + Consider the example module "example-module" from Section 3.4 that is hypothetically available in the following revision/label pairings: 2019-01-01/1.0.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-04-01/2.1.0, 2019-05-01/2.2.0 and 2019-06-01/3.1.0. The @@ -893,9 +781,9 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 -Wilton, et al. Expires 9 June 2023 [Page 16] +Wilton, et al. Expires 18 May 2024 [Page 14] -Internet-Draft Updated YANG Module Revision Handling December 2022 +Internet-Draft Updated YANG Module Revision Handling November 2023 import example-module { @@ -935,89 +823,32 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 5. Updates to ietf-yang-library - This document updates YANG 1.1 [RFC7950] and YANG library [RFC8525] - to clarify how ambiguous module imports are resolved. It also - defines the YANG module, ietf-yang-library-revisions, that augments - YANG library [RFC8525] with revision labels and two leafs to indicate - how a server implements deprecated and obsolete schema nodes. - + This document defines the YANG module, ietf-yang-library-revisions, + that augments YANG library [RFC8525] with two leafs to indicate how a + server implements deprecated and obsolete schema nodes. +5.1. YANG library versioning augmentations + The "ietf-yang-library-revisions" YANG module has the following + structure (using the notation defined in [RFC8340]): -Wilton, et al. Expires 9 June 2023 [Page 17] +Wilton, et al. Expires 18 May 2024 [Page 15] -Internet-Draft Updated YANG Module Revision Handling December 2022 - - -5.1. Resolving ambiguous module imports - - A YANG datastore schema, defined in [RFC8525], can specify multiple - revisions of a YANG module in the schema using the "import-only" - list, with the requirement from [RFC7950] section 5.6.5 that only a - single revision of a YANG module may be implemented. - - If a YANG module import statement does not specify a specific - revision within the datastore schema then it could be ambiguous as to - which module revision the import statement should resolve to. Hence, - a datastore schema constructed by a client using the information - contained in YANG library may not exactly match the datastore schema - actually used by the server. - - The following two rules remove the ambiguity: - - If a module import statement could resolve to more than one module - revision defined in the datastore schema, and one of those revisions - is implemented (i.e., not an "import-only" module), then the import - statement MUST resolve to the revision of the module that is defined - as being implemented by the datastore schema. - - If a module import statement could resolve to more than one module - revision defined in the datastore schema, and none of those revisions - are implemented, then the import MUST resolve to the module revision - with the latest revision date. - -5.2. YANG library versioning augmentations - - - The "ietf-yang-library-revisions" YANG module has the following - structure (using the notation defined in [RFC8340]): +Internet-Draft Updated YANG Module Revision Handling November 2023 module: ietf-yang-library-revisions - augment /yanglib:yang-library/yanglib:module-set/yanglib:module: - +--ro revision-label? rev:revision-label - augment /yanglib:yang-library/yanglib:module-set/yanglib:module - /yanglib:submodule: - +--ro revision-label? rev:revision-label - augment /yanglib:yang-library/yanglib:module-set - /yanglib:import-only-module/yanglib:submodule: - +--ro revision-label? rev:revision-label augment /yanglib:yang-library/yanglib:schema: +--ro deprecated-nodes-implemented? boolean +--ro obsolete-nodes-absent? boolean - - - -Wilton, et al. Expires 9 June 2023 [Page 18] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - -5.2.1. Advertising revision-label - - The ietf-yang-library-revisions YANG module augments the "module" and - "submodule" lists in ietf-yang-library with "revision-label" leafs to - optionally declare the revision label associated with each module and - submodule. - -5.2.2. Reporting how deprecated and obsolete nodes are handled +5.1.1. Reporting how deprecated and obsolete nodes are handled The ietf-yang-library-revisions YANG module augments YANG library with two boolean leafs to allow a server to report how it implements @@ -1046,44 +877,27 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 any nodes has changed to "deprecated" and whether those nodes are implemented by the server. -6. Versioning of YANG instance data - - Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not - directly make use of the updated revision handling rules described in - this document, as compatibility for instance data is undefined. - - However, instance data specifies the content-schema of the data-set. - This schema SHOULD make use of versioning using revision dates and/or - revision labels for the individual YANG modules that comprise the - schema or potentially for the entire schema itself (e.g., - [I-D.ietf-netmod-yang-packages]). - - - - -Wilton, et al. Expires 9 June 2023 [Page 19] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - - In this way, the versioning of a content-schema associated with an - instance data set may help a client to determine whether the instance - data could also be used in conjunction with other revisions of the - YANG schema, or other revisions of the modules that define the - schema. - -7. Guidelines for using the YANG module update rules +6. Guidelines for using the YANG module update rules The following text updates section 4.7 of [RFC8407] to revise the guidelines for updating YANG modules. -7.1. Guidelines for YANG module authors +6.1. Guidelines for YANG module authors All IETF YANG modules MUST include revision label statements for all newly published YANG modules, and all newly published revisions of existing YANG modules. The revision label MUST take the form of a YANG semantic version number [I-D.ietf-netmod-yang-semver]. + + + + +Wilton, et al. Expires 18 May 2024 [Page 16] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + NBC changes to YANG modules may cause problems to clients, who are consumers of YANG models, and hence YANG module authors SHOULD minimize NBC changes and keep changes BC whenever possible. @@ -1113,15 +927,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 the including module MUST be updated when any included submodule has changed. - - - - -Wilton, et al. Expires 9 June 2023 [Page 20] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - In some cases a module or submodule revision that is not strictly NBC by the definition in Section 3.1.2 of this specification may include the "non-backwards-compatible" statement. Here is an example when @@ -1133,7 +938,7 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 compatibility impact for clients and users of the module or submodule -7.1.1. Making non-backwards-compatible changes to a YANG module +6.1.1. Making non-backwards-compatible changes to a YANG module There are various valid situations where a YANG module has to be modified in an NBC way. Here are some guidelines on how non- @@ -1141,13 +946,21 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 assumption that deprecated nodes are implemented by the server, and obsolete nodes are not: + + + +Wilton, et al. Expires 18 May 2024 [Page 17] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + 1. The changes should be made gradually, e.g., a data node's status SHOULD NOT be changed directly from "current" to "obsolete" (see Section 4.7 of [RFC8407]), instead the status SHOULD first be marked "deprecated". At some point in the future, when support is removed for the data node, there are two options. The first, and preferred, option is to keep the data node definition in the - model and change the status to "obsolete". The second option is + model and change the status to “obsolete”. The second option is to simply remove the data node from the model, but this has the risk of breaking modules which import the modified module, and the removed identifier may be accidently reused in a future @@ -1165,19 +978,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 information, from when the node had status "deprecated", which is still relevant. - - - - - - - - -Wilton, et al. Expires 9 June 2023 [Page 21] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - 4. When obsoleting or deprecating data nodes, the "deprecated" or "obsolete" status SHOULD be applied at the highest possible level in the data tree. For clarity, the "status" statement SHOULD @@ -1197,11 +997,19 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 See Appendix B for examples on how NBC changes can be made. -7.2. Versioning Considerations for Clients +6.2. Versioning Considerations for Clients Guidelines for clients of modules using the new module revision update procedure: + + + +Wilton, et al. Expires 18 May 2024 [Page 18] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + * Clients SHOULD be liberal when processing data received from a server. For example, the server may have increased the range of an operational node causing the client to receive a value which is @@ -1219,35 +1027,17 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 timely fashion. When a node's status changes to "obsolete", clients MUST stop using that node. -8. Module Versioning Extension YANG Modules - - YANG module with extension statements for annotating NBC changes, - revision label, revision label scheme, and importing by revision. - - - - - - -Wilton, et al. Expires 9 June 2023 [Page 22] - -Internet-Draft Updated YANG Module Revision Handling December 2022 +7. Module Versioning Extension YANG Modules + YANG module with extension statements for annotating NBC changes and + importing by revision. - file "ietf-yang-revisions@2022-15-11.yang" + file "ietf-yang-revisions@2023-11-15.yang" module ietf-yang-revisions { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions"; prefix rev; - // RFC Ed.: We need the bis version to get the new type revision-identifier - // If 6991-bis is not yet an RFC we need to copy the definition here - import ietf-yang-types { - prefix yang; - reference - "XXXX [ietf-netmod-rfc6991-bis]: Common YANG Data Types"; - } - organization "IETF NETMOD (Network Modeling) Working Group"; contact @@ -1268,6 +1058,14 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Author: Jason Sterne "; + + + +Wilton, et al. Expires 18 May 2024 [Page 19] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + description "This YANG 1.1 module contains definitions and extensions to support updated YANG revision handling. @@ -1282,14 +1080,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Relating to IETF Documents (http://trustee.ietf.org/license-info). - - - -Wilton, et al. Expires 9 June 2023 [Page 23] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices. @@ -1304,49 +1094,33 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 // RFC Ed.: replace XXXX (inc above) with actual RFC number and // remove this note. - revision 2022-15-11 { - rev:label 1.0.0-draft-ietf-netmod-yang-module-versioning-08; + revision 2023-11-15 { + rev:label 1.0.0-draft-ietf-netmod-yang-module-versioning-11; description "Initial version."; reference "XXXX: Updated YANG Module Revision Handling"; } - typedef revision-label { + typedef revision-date { type string { - length "1..255"; - pattern '[a-zA-Z0-9,\-_.+]+'; - pattern '\d{4}-\d{2}-\d{2}' { - modifier invert-match; - } + pattern '[0-9]{4}-(1[0-2]|0[1-9])-(0[1-9]|[1-2][0-9]|3[0-1])'; } description - "A label associated with a YANG revision. + "A date associated with a YANG revision. - Alphanumeric characters, comma, hyphen, underscore, period - and plus are the only accepted characters. MUST NOT match - revision-date."; + Matches dates formatted as YYYY-MM-DD."; reference - "XXXX: Updated YANG Module Revision Handling; - Section 3.3, Revision label"; + "RFC 7950: The YANG 1.1 Data Modeling Language"; } - typedef revision-date-or-label { - type union { - type yang:revision-identifier; - type revision-label; - } - description - "Represents either a YANG revision date or a revision label"; -Wilton, et al. Expires 9 June 2023 [Page 24] +Wilton, et al. Expires 18 May 2024 [Page 20] -Internet-Draft Updated YANG Module Revision Handling December 2022 - +Internet-Draft Updated YANG Module Revision Handling November 2023 - } extension non-backwards-compatible { description @@ -1385,135 +1159,46 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Section 3.2, non-backwards-compatible revision extension statement"; } - extension label { - argument revision-label; + extension recommended-min-date { + argument revision-date; description - "The revision label can be used to provide an additional - versioning identifier associated with a module or submodule - revision. One such scheme that - could be used is [XXXX: ietf-netmod-yang-semver]. + "Recommends the revision of the module that may be imported to + one that matches or is derived from the specified + revision-date or revision label. + + The argument value MUST conform to the + 'revision-date-or-label' defined type. - The format of the revision label argument MUST conform to the + The statement MUST only be a substatement of the import -Wilton, et al. Expires 9 June 2023 [Page 25] +Wilton, et al. Expires 18 May 2024 [Page 21] -Internet-Draft Updated YANG Module Revision Handling December 2022 +Internet-Draft Updated YANG Module Revision Handling November 2023 - pattern defined for the revision label typedef in this module. + statement. Zero, one or more 'recommended-min' statements + per parent statement are allowed. No substatements for this + extension have been standardized. - The statement MUST only be a substatement of the revision - statement. Zero or one revision label statements per parent - statement are allowed. No substatements for this extension - have been standardized. + If specified multiple times, then any module revision that + satisfies at least one of the 'recommended-min' statements + is an acceptable recommended revision for import. - Revision labels MUST be unique amongst all revisions of a - module or submodule. - - Adding a revision label is a backwards-compatible version - change. Changing or removing an existing revision label in - the revision history is a non-backwards-compatible version - change, because it could impact any references to that - revision label."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 3.3, Revision label"; - } - - extension revision-label-scheme { - argument revision-label-scheme-base; - description - "The revision label scheme specifies which revision label scheme - the module or submodule uses. - - The mandatory revision-label-scheme-base argument MUST be an - identity derived from revision-label-scheme-base. - - This extension is only valid as a top-level statement, i.e., - given as as a substatement to 'module' or 'submodule'. No - substatements for this extension have been standardized. - - This extension MUST be used if there is a revision label - statement in the module or submodule. - - Adding a revision label scheme is a backwards-compatible version - change. Changing a revision label scheme is a - non-backwards-compatible version change, unless the new revision - label scheme is backwards-compatible with the replaced revision - label scheme. Removing a revision label scheme is a - non-backwards-compatible version change."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 3.3.1, Revision label scheme extension statement"; - } - - - -Wilton, et al. Expires 9 June 2023 [Page 26] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - - extension recommended-min { - argument revision-date-or-label; - description - "Recommends the revision of the module that may be imported to - one that matches or is derived from the specified - revision-date or revision label. - - The argument value MUST conform to the - 'revision-date-or-label' defined type. - - The statement MUST only be a substatement of the import - statement. Zero, one or more 'recommended-min' statements - per parent statement are allowed. No substatements for this - extension have been standardized. - - If specified multiple times, then any module revision that - satisfies at least one of the 'recommended-min' statements - is an acceptable recommended revision for import. - - A particular revision of an imported module adheres to an - import's 'recommended-min' extension statement if the - imported module's revision history contains a revision - statement with a matching revision date or revision label. + A particular revision of an imported module adheres to an + import's 'recommended-min' extension statement if the + imported module's revision history contains a revision + statement with a matching revision date or revision label. Adding, removing or updating a 'recommended-min' - statement to an import is a backwards-compatible change. - "; + statement to an import is a backwards-compatible change."; reference "XXXX: Updated YANG Module Revision Handling; Section 4, Recommending a minimum revision for module imports"; } - - identity revision-label-scheme-base { - description - "Base identity from which all revision label schemes are - derived."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 3.3.1, Revision label scheme extension statement"; - - } - - - - } - - - -Wilton, et al. Expires 9 June 2023 [Page 27] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - YANG module with augmentations to YANG Library to revision labels @@ -1525,12 +1210,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 "urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions"; prefix yl-rev; - import ietf-yang-revisions { - prefix rev; - reference - "XXXX: Updated YANG Module Revision Handling"; - } - import ietf-yang-library { prefix yanglib; reference "RFC 8525: YANG Library"; @@ -1548,6 +1227,13 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Author: Reshad Rahman + + +Wilton, et al. Expires 18 May 2024 [Page 22] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + Author: Robert Wilton @@ -1562,14 +1248,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 deprecated and obsolete nodes are handled by the server. Copyright (c) 2021 IETF Trust and the persons identified as - - - -Wilton, et al. Expires 9 June 2023 [Page 28] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or @@ -1602,94 +1280,16 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 "XXXX: Updated YANG Module Revision Handling"; } - // library 1.0 modules-state is not augmented with revision-label - - augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { - description - "Add a revision label to module information"; - leaf revision-label { - type rev:revision-label; - description - "The revision label associated with this module revision. - The label MUST match the revision label value in the specific - revision of the module loaded in this module-set."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 5.2.1, Advertising revision-label"; - } - - - -Wilton, et al. Expires 9 June 2023 [Page 29] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - - } - - augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/" - + "yanglib:submodule" { - description - "Add a revision label to submodule information"; - leaf revision-label { - type rev:revision-label; - description - "The revision label associated with this submodule revision. - The label MUST match the revision label value in the specific - revision of the submodule included by the module loaded in - this module-set."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 5.2.1, Advertising revision-label"; - } - } - - augment "/yanglib:yang-library/yanglib:module-set/" - + "yanglib:import-only-module" { - description - "Add a revision label to module information"; - leaf revision-label { - type rev:revision-label; - description - "The revision label associated with this module revision. - The label MUST match the revision label value in the specific - revision of the module included in this module-set."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 5.2.1, Advertising revision-label"; - } - } - - augment "/yanglib:yang-library/yanglib:module-set/" - + "yanglib:import-only-module/yanglib:submodule" { + augment "/yanglib:yang-library/yanglib:schema" { description - "Add a revision label to submodule information"; - leaf revision-label { - type rev:revision-label; - description - "The revision label associated with this submodule revision. - The label MUST match the rev:label value in the specific - revision of the submodule included by the - import-only-module loaded in this module-set."; -Wilton, et al. Expires 9 June 2023 [Page 30] +Wilton, et al. Expires 18 May 2024 [Page 23] -Internet-Draft Updated YANG Module Revision Handling December 2022 +Internet-Draft Updated YANG Module Revision Handling November 2023 - reference - "XXXX: Updated YANG Module Revision Handling; - Section 5.2.1, Advertising revision-label"; - } - } - - augment "/yanglib:yang-library/yanglib:schema" { - description "Augmentations to the ietf-yang-library module to indicate how deprecated and obsoleted nodes are handled for each datastore schema supported by the server."; @@ -1726,84 +1326,25 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 } +8. Security considerations +8.1. Security considerations for module revisions + As discussed in the introduction of this document, YANG modules + occasionally undergo changes that are not backwards compatible. This + occurs in both standards and vendor YANG modules despite the + prohibitions in RFC 7950. RFC 7950 also allows nodes to change to + status 'obsolete' which can change behavior and compatibility for a + client. -Wilton, et al. Expires 9 June 2023 [Page 31] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - -9. Contributors - - This document grew out of the YANG module versioning design team that - started after IETF 101. The following individuals are (or have been) - members of the design team and have worked on the YANG versioning - project: - - * Balazs Lengyel - - * Benoit Claise - - * Bo Wu - - * Ebben Aries - - * Jan Lindblad - - * Jason Sterne - - * Joe Clarke - - * Juergen Schoenwaelder - - * Mahesh Jethanandani - - * Michael (Wangzitao) - - * Qin Wu - - * Reshad Rahman - - * Rob Wilton - - The initial revision of this document was refactored and built upon - [I-D.clacla-netmod-yang-model-update]. We would like to thank Kevin - D'Souza and Benoit Claise for their initial work in this problem - space. - - Discussons on the use of Semver for YANG versioning has been held - with authors of the OpenConfig YANG models. We would like to thank - both Anees Shaikh and Rob Shakir for their input into this problem - space. - - We would also like to thank Lou Berger, Andy Bierman, Martin - Bjorklund, Italo Busi, Tom Hill, Scott Mansfield, Kent Watsen for - their contributions and review comments. - - - - - -Wilton, et al. Expires 9 June 2023 [Page 32] +Wilton, et al. Expires 18 May 2024 [Page 24] -Internet-Draft Updated YANG Module Revision Handling December 2022 - +Internet-Draft Updated YANG Module Revision Handling November 2023 -10. Security considerations - -10.1. Security considerations for module revisions - - As discussed in the introduction of this document, YANG modules - occasionally undergo changes that are not backwards compatible. This - occurs in both standards and vendor YANG modules despite the - prohibitions in RFC 7950. RFC 7950 also allows nodes to change to - status 'obsolete' which can change behavior and compatibility for a - client. The fact that YANG modules change in a non-backwards-compatible manner may have security implications. Such changes should be @@ -1835,22 +1376,7 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 it is recommended to highlight those implications in the description of the revision statement. - - - - - - - - - - -Wilton, et al. Expires 9 June 2023 [Page 33] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - -10.2. Security considerations for the modules defined in this document +8.2. Security considerations for the modules defined in this document The YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such @@ -1868,16 +1394,23 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 This document does not define any new protocol or data nodes that are writable. + + + +Wilton, et al. Expires 18 May 2024 [Page 25] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + This document updates YANG Library [RFC8525] with augmentations to - include revision labels in the YANG library data and two boolean - leafs to indicate whether status deprecated and status obsolete - schema nodes are implemented by the server. These read-only - augmentations do not add any new security considerations beyond those - already present in [RFC8525]. + include two boolean leafs that indicate whether status deprecated and + status obsolete schema nodes are implemented by the server. These + read-only augmentations do not add any new security considerations + beyond those already present in [RFC8525]. -11. IANA Considerations +9. IANA Considerations -11.1. YANG Module Registrations +9.1. YANG Module Registrations This document requests IANA to registers a URI in the "IETF XML Registry" [RFC3688]. Following the format in RFC 3688, the following @@ -1899,13 +1432,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Name: ietf-yang-revisions - - -Wilton, et al. Expires 9 June 2023 [Page 34] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-revisions Prefix: rev @@ -1923,7 +1449,16 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Reference: [RFCXXXX] -11.2. Guidance for versioning in IANA maintained YANG modules + + + + +Wilton, et al. Expires 18 May 2024 [Page 26] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + +9.2. Guidance for versioning in IANA maintained YANG modules Note for IANA (to be removed by the RFC editor): Please check that the registries and IANA YANG modules are referenced in the @@ -1951,17 +1486,6 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 maintained module is updated in a non-backwards-compatible way, as described in Section 3.2. - - - - - - -Wilton, et al. Expires 9 June 2023 [Page 35] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - Note: For published IANA maintained YANG modules that contain non- backwards-compatible changes between revisions, a new revision should be published with the "rev:non-backwards-compatible" substatement @@ -1982,6 +1506,14 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 description of an enumeration that does not change its defined meaning. + + + +Wilton, et al. Expires 18 May 2024 [Page 27] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + Non-normative examples of updates to identity types in IANA maintained modules that would be classified as non-backwards- compatible changes are: Changing the status of an identity to @@ -1994,29 +1526,17 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 identity to deprecated, or improving the description of an identity that does not change its defined meaning. -12. References +10. References -12.1. Normative References - - [I-D.ietf-netmod-rfc6991-bis] - Schönwälder, J., "Common YANG Data Types", Work in - Progress, Internet-Draft, draft-ietf-netmod-rfc6991-bis- - 14, 5 December 2022, . +10.1. Normative References [I-D.ietf-netmod-yang-semver] Clarke, J., Wilton, R., Rahman, R., Lengyel, B., Sterne, J., and B. Claise, "YANG Semantic Versioning", Work in Progress, Internet-Draft, draft-ietf-netmod-yang-semver- - 08, 24 October 2022, . - - - -Wilton, et al. Expires 9 June 2023 [Page 36] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - + 12, 2 October 2023, + . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, @@ -2041,6 +1561,15 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, . + + + + +Wilton, et al. Expires 18 May 2024 [Page 28] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . @@ -2067,19 +1596,12 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . - - -Wilton, et al. Expires 9 June 2023 [Page 37] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., and R. Wilton, "YANG Library", RFC 8525, DOI 10.17487/RFC8525, March 2019, . -12.2. Informative References +10.2. Informative References [AddrFamilyReg] "Address Family Numbers IANA Registry", @@ -2090,59 +1612,58 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New YANG Module Update Procedure", Work in Progress, Internet- Draft, draft-clacla-netmod-yang-model-update-06, 2 July - 2018, . + 2018, . [I-D.ietf-netmod-yang-instance-file-format] Lengyel, B. and B. Claise, "A File Format for YANG Instance Data", Work in Progress, Internet-Draft, draft- + + + +Wilton, et al. Expires 18 May 2024 [Page 29] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + ietf-netmod-yang-instance-file-format-21, 8 October 2021, - . + . [I-D.ietf-netmod-yang-packages] Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, "YANG Packages", Work in Progress, Internet-Draft, draft- ietf-netmod-yang-packages-03, 4 March 2022, - . + . [I-D.ietf-netmod-yang-schema-comparison] - Wilton, R., "YANG Schema Comparison", Work in Progress, - Internet-Draft, draft-ietf-netmod-yang-schema-comparison- - 01, 2 November 2020, . + Andersson, P. and R. Wilton, "YANG Schema Comparison", + Work in Progress, Internet-Draft, draft-ietf-netmod-yang- + schema-comparison-02, 14 March 2023, + . [I-D.ietf-netmod-yang-solutions] Wilton, R., "YANG Versioning Solution Overview", Work in Progress, Internet-Draft, draft-ietf-netmod-yang- solutions-01, 2 November 2020, - . - - - - - - -Wilton, et al. Expires 9 June 2023 [Page 38] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - + . [I-D.ietf-netmod-yang-ver-selection] Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, "YANG Schema Selection", Work in Progress, Internet-Draft, draft-ietf-netmod-yang-ver-selection-00, 17 March 2020, - . + . [I-D.ietf-netmod-yang-versioning-reqs] Clarke, J., "YANG Module Versioning Requirements", Work in Progress, Internet-Draft, draft-ietf-netmod-yang- - versioning-reqs-07, 10 July 2022, - . + versioning-reqs-08, 26 June 2023, + . [IfTypesReg] "Interface Types (ifType) IANA Registry", @@ -2154,6 +1675,13 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 . + + +Wilton, et al. Expires 18 May 2024 [Page 30] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . @@ -2178,14 +1706,6 @@ Appendix A. Examples of changes that are NBC Examples of NBC changes include: - - - -Wilton, et al. Expires 9 June 2023 [Page 39] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - * Deleting a data node, or changing it to status obsolete. * Changing the name, type, or units of a data node. @@ -2207,10 +1727,17 @@ Appendix B. Examples of applying the NBC change guidelines The following sections give steps that could be taken for making NBC changes to a YANG module or submodule using the incremental approach - described in section Section 7.1.1. + described in section Section 6.1.1. The examples are all for "config true" nodes. + + +Wilton, et al. Expires 18 May 2024 [Page 31] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + B.1. Removing a data node Removing a leaf or container from the data tree, e.g., because @@ -2232,15 +1759,7 @@ B.2. Changing the type of a leaf node 1. The status of schema node "vpn-id" is changed to "deprecated" and the node is supported for some period of time (e.g. one year). This is a BC change. The description is updated to indicate that - "vpn-name" is replacing this node. - - - - -Wilton, et al. Expires 9 June 2023 [Page 40] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - + “vpn-name” is replacing this node. 2. A new schema node, e.g., "vpn-name", of type string is added to the same location as the existing node "vpn-id". This new node @@ -2263,6 +1782,18 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 status is changed to "obsolete" and the "description" is updated. This is an NBC change. + + + + + + + +Wilton, et al. Expires 18 May 2024 [Page 32] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + B.3. Reducing the range of a leaf node Reducing the range of values of a leaf-node, e.g., consider a "vpn- @@ -2288,16 +1819,6 @@ B.4. Changing the key of a list there is a need to change the key to "dest-address". Such a change can be done in steps: - - - - - -Wilton, et al. Expires 9 June 2023 [Page 41] - -Internet-Draft Updated YANG Module Revision Handling December 2022 - - 1. The status of list "sessions" is changed to "deprecated" and the list is supported for some period of time (e.g. one year). This is a BC change. The description is updated to indicate the new @@ -2321,6 +1842,14 @@ Internet-Draft Updated YANG Module Revision Handling December 2022 changed to "obsolete" and the "description" is updated. This is an NBC change. + + + +Wilton, et al. Expires 18 May 2024 [Page 33] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + B.5. Renaming a node A leaf or container schema node may be renamed, either due to a @@ -2337,6 +1866,27 @@ B.5. Renaming a node "current" and its description should explain that it is replacing node "ip-adress". + 3. During the period of time when both nodes are available, the + interactions between the two nodes is outside the scope of this + document and will vary on a case by case basis. One possible + option is to have the server prevent the new node from being set + if the old node is already set (and vice-versa). The new node + could have a "when" statement added to it to achieve this. The + old node, however, must not have a "when" statement added, or an + existing "when" modified to be more restrictive, since this would + be an NBC change. In any case, the server could reject the old + node from being set if the new node is already set. + + 4. When node "ip-adress" is not available anymore, its status is + changed to "obsolete" and the "description" is updated. This is + an NBC change. + +Contributors + + This document grew out of the YANG module versioning design team that + started after IETF 101. The authors and the following individuals + are (or have been) members of the design team and have worked on the + YANG versioning project: @@ -2349,25 +1899,53 @@ B.5. Renaming a node -Wilton, et al. Expires 9 June 2023 [Page 42] + + +Wilton, et al. Expires 18 May 2024 [Page 34] -Internet-Draft Updated YANG Module Revision Handling December 2022 +Internet-Draft Updated YANG Module Revision Handling November 2023 - 3. During the period of time when both nodes are available, the - interactions between the two nodes is outside the scope of this - document and will vary on a case by case basis. One possible - option is to have the server prevent the new node from being set - if the old node is already set (and vice-versa). The new node - could have a "when" statement added to it to achieve this. The - old node, however, must not have a "when" statement added, or an - existing "when" modified to be more restrictive, since this would - be an NBC change. In any case, the server could reject the old - node from being set if the new node is already set. + Benoit Claise + benoit.claise@huawei.com - 4. When node "ip-adress" is not available anymore, its status is - changed to "obsolete" and the "description" is updated. This is - an NBC change. + Bo Wu + lana.wubo@huawei.com + + Ebben Aries + exa@juniper.net + + Jan Lindblad + lindbla@cisco.com + + Juergen Schoenwaelder + j.shoenwaelder@jacobs-university.de + + Mahesh Jethanandani + mjethanandani@gmail.com + + Michael (Wangzitao) + wangzitao@huawei.com + + Per Andersson + perander@cisco.com + + Qin Wu + bill.wu@huawei.com + + The initial revision of this document was refactored and built upon + [I-D.clacla-netmod-yang-model-update]. We would like to thank Kevin + D'Souza and Benoit Claise for their initial work in this problem + space. + + Discussions on the use of Semver for YANG versioning has been held + with authors of the OpenConfig YANG models. We would like to thank + both Anees Shaikh and Rob Shakir for their input into this problem + space. + + We would also like to thank Lou Berger, Andy Bierman, Martin + Bjorklund, Italo Busi, Tom Hill, Scott Mansfield, and Kent Watsen for + their contributions and review comments. Authors' Addresses @@ -2376,6 +1954,14 @@ Authors' Addresses Email: rwilton@cisco.com + + + +Wilton, et al. Expires 18 May 2024 [Page 35] + +Internet-Draft Updated YANG Module Revision Handling November 2023 + + Reshad Rahman (editor) Email: reshad@yahoo.com @@ -2405,4 +1991,26 @@ Authors' Addresses -Wilton, et al. Expires 9 June 2023 [Page 43] + + + + + + + + + + + + + + + + + + + + + + +Wilton, et al. Expires 18 May 2024 [Page 36] diff --git a/yang-module-versioning/draft-ietf-netmod-yang-module-versioning.xml b/yang-module-versioning/draft-ietf-netmod-yang-module-versioning.xml index f195707..92e3e15 100644 --- a/yang-module-versioning/draft-ietf-netmod-yang-module-versioning.xml +++ b/yang-module-versioning/draft-ietf-netmod-yang-module-versioning.xml @@ -23,7 +23,7 @@ - + Updated YANG Module Revision Handling @@ -91,14 +91,12 @@ This document defines a flexible versioning solution. Several other documents build on this solution with additional capabilities. specifies an algorithm that can be used to compare two revisions of a YANG schema and provide granular information to allow module users to determine if they are impacted by changes between the revisions. The document extends the module versioning work by introducing a revision label scheme based on semantic versioning. YANG packages provides a mechanism to group sets of related YANG modules together in order to manage schema and conformance of YANG modules as a cohesive set instead of individually. Finally, provides a schema selection mechanism that allows a client to choose which schemas to use when interacting with a server from the available schema that are supported and advertised by the server. These other documents are mentioned here as informative references. Support of the other documents is not required in an implementation in order to take advantage of the mechanisms and functionality offered by this module versioning document. - The document comprises five parts: + The document comprises four parts: Refinements to the YANG 1.1 module revision update procedure, supported by new extension statements to indicate - when a revision contains non-backwards-compatible changes, and an optional revision label. + when a revision contains non-backwards-compatible changes. Updated guidance for revision selection on imports and a YANG extension statement allowing YANG module imports to document an earliest module revision that may satisfy the import dependency. - Updates and augmentations to ietf-yang-library to include the revision label in the module and submodule descriptions, to - report how "deprecated" and "obsolete" nodes are handled by a server, and to clarify how module imports are resolved - when multiple revisions could otherwise be chosen. + Updates and augmentations to ietf-yang-library to report how "deprecated" and "obsolete" nodes are handled by a server. Guidelines for how the YANG module update rules defined in this document should be used, along with examples. @@ -110,35 +108,31 @@ This document updates section 11 and section 10. describes modifications to YANG revision handling and update rules, and describes a YANG extension statement to describe potential YANG import revision dependencies. - This document updates section 5.2, section 5.2 and section 3.2. - describes the use of a revision - label in the name of a file containing a YANG module or submodule. This document updates section 4.7. provides guidelines on managing the lifecycle of YANG modules that may contain non-backwards-compatible changes and a branched revision history. - This document updates with augmentations to include revision labels in the YANG library data and two - boolean leafs to indicate whether status deprecated and status obsolete schema nodes are implemented by the server. + This document updates with augmentations to include two boolean leafs to indicate whether status deprecated and status obsolete schema nodes are implemented by the server. -
- 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 when, and only when, they appear in all capitals, as shown here. - This document makes use of the following terminology introduced in - the YANG 1.1 Data Modeling Language : - schema node - - In addition, this document uses the following terminology: - - YANG module revision: An instance of a YANG module, uniquely identified with a revision date, with no implied - ordering or backwards compatibility between different revisions of the same module. - Backwards-compatible (BC) change: A backwards-compatible change between two YANG module revisions, as defined - in - Non-backwards-compatible (NBC) change: A non-backwards-compatible change between two YANG module revisions, as - defined in - - -
+
+ 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 when, and only when, they appear in all capitals, as shown here. + This document makes use of the following terminology introduced in + the YANG 1.1 Data Modeling Language : + schema node + + In addition, this document uses the following terminology: + + YANG module revision: An instance of a YANG module, uniquely identified with a revision date, with no implied + ordering or backwards compatibility between different revisions of the same module. + Backwards-compatible (BC) change: A backwards-compatible change between two YANG module revisions, as defined + in + Non-backwards-compatible (NBC) change: A non-backwards-compatible change between two YANG module revisions, as + defined in + + +
and assume, but do not explicitly state, that the revision history for a YANG module or submodule is @@ -273,62 +267,6 @@ revision 2019-01-02 { In the revision history example above, removing the revision history entry for 2020-02-10 would also remove the rev:non-backwards-compatible annotation and hence the resulting revision history would incorrectly indicate that revision 2020-06-07 is backwards-compatible with revisions 2019-01-02 through 2019-10-21 when it is not, and so this change cannot be made. Conversely, removing one or more revisions out of 2019-03-04, 2019-10-21 and 2020-08-09 from the revision history would still retain a consistent revision history, and is acceptable, subject to an awareness of the concerns raised in the first paragraph of this section.
-
- Each revision entry in a module or submodule MAY have a revision label associated with it, providing an - alternative alias to identify a particular revision of a module or submodule. The revision label could be used to - provide an additional versioning identifier associated with the revision. - A revision label scheme is a set of rules describing how a particular type of revision label operates for versioning YANG modules and submodules. - For example, YANG Semver - defines a revision label scheme based on Semver 2.0.0 . - Other documents may define other YANG revision label schemes. - Submodules MAY use a revision label scheme. When they use a revision - label scheme, submodules MAY use a revision label scheme that is different from - the one used in the including module. - The revision label space of submodules is separate from the revision label space of the including module. - A change in one submodule MUST result in a new revision label of that submodule and the including module, - but the actual values of the revision labels in the module and submodule could be completely different. A - change in one submodule does not result in a new revision label in another submodule. A change in a module - revision label does not necessarily mean a change to the revision label in all included submodules. - If a revision has an associated revision label, then it may be used - instead of the revision date in a "rev:recommended-min" extension - statement argument. - - A specific revision label identifies a specific revision of the - module. If two YANG modules contain the same module name and the same - revision label (and hence also the same revision-date) in their latest revision statement, - then the file contents of the two modules, including the revision history, MUST be identical. -
- This section updates section 5.2, section 5.2 and section 3.2 - If a revision has an associated revision label, then it is RECOMMENDED that the name of the file for that revision be of the form: -
- - - -
- YANG module (or submodule) files may be identified using either the revision-date (as per section 3.2) or the revision label. - -
- -
- The optional "rev:revision-label-scheme" extension statement is used to indicate which revision label - scheme a module or submodule uses. There MUST NOT be more than one revision label scheme in a module or submodule. The mandatory argument to this extension statement: - - specifies the revision label scheme used by the module or submodule - is defined in the document which specifies the revision label scheme - MUST be an identity derived from "revision-label-scheme-base". - - - The revision label scheme used by a module or submodule SHOULD NOT change during the - lifetime of the module or submodule. If the revision label scheme used by a module or submodule - is changed to a new scheme, then all revision label statements that do not - conform to the new scheme MUST be replaced or removed. -
-
-
The following diagram, explanation, and module history illustrates how the branched revision history, "non-backwards-compatible" extension statement, and revision "label" extension statement could be used: @@ -537,8 +475,7 @@ import example-module {
- This document defines the YANG module, ietf-yang-library-revisions, that augments YANG library with - revision labels and two leafs to indicate how a server implements deprecated and obsolete schema nodes. + This document defines the YANG module, ietf-yang-library-revisions, that augments YANG library with two leafs to indicate how a server implements deprecated and obsolete schema nodes.
@@ -548,14 +485,6 @@ import example-module { -
- The ietf-yang-library-revisions YANG module augments the "module" and "submodule" lists in ietf-yang-library with "revision-label" - leafs to optionally declare the revision label associated with each module and submodule. -
The ietf-yang-library-revisions YANG module augments YANG library with two boolean leafs to allow a server to report how it implements status "deprecated" and status "obsolete" schema nodes. The leafs are: @@ -660,10 +585,9 @@ module: ietf-yang-library-revisions
- YANG module with extension statements for annotating NBC changes, revision label, revision label scheme, - and importing by revision. - file "ietf-yang-revisions@2022-11-29.yang" + YANG module with extension statements for annotating NBC changes and importing by revision. + file "ietf-yang-revisions@2023-11-15.yang" module ietf-yang-revisions { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions"; @@ -717,8 +641,8 @@ module ietf-yang-revisions { // RFC Ed.: replace XXXX (inc above) with actual RFC number and // remove this note. - revision 2022-11-29 { - rev:label 1.0.0-draft-ietf-netmod-yang-module-versioning-08; + revision 2023-11-15 { + rev:label 1.0.0-draft-ietf-netmod-yang-module-versioning-11; description "Initial version."; reference @@ -737,36 +661,6 @@ module ietf-yang-revisions { "RFC 7950: The YANG 1.1 Data Modeling Language"; } - typedef revision-label { - type string { - length "1..255"; - pattern '[a-zA-Z0-9,\-_.+]+'; - pattern '[0-9]{4}-[0-9]{2}-[0-9]{2}' { - error-message - "The revision-label must not match a revision-date."; - modifier invert-match; - } - } - description - "A label associated with a YANG revision. - - Alphanumeric characters, comma, hyphen, underscore, period - and plus are the only accepted characters. MUST NOT match - revision-date or pattern similar to a date."; - reference - "XXXX: Updated YANG Module Revision Handling; - Section 3.3, Revision label"; - } - - typedef revision-date-or-label { - type union { - type revision-date; - type revision-label; - } - description - "Represents either a YANG revision date or a revision label"; - } - extension non-backwards-compatible { description "This statement is used to indicate YANG module revisions that @@ -804,66 +698,8 @@ module ietf-yang-revisions { Section 3.2, non-backwards-compatible revision extension statement"; } - extension label { - argument revision-label; - description - "The revision label can be used to provide an additional - versioning identifier associated with a module or submodule - revision. One such scheme that - could be used is [XXXX: ietf-netmod-yang-semver]. - - The format of the revision label argument MUST conform to the - pattern defined for the revision label typedef in this module. - - The statement MUST only be a substatement of the revision - statement. Zero or one revision label statements per parent - statement are allowed. No substatements for this extension - have been standardized. - - Revision labels MUST be unique amongst all revisions of a - module or submodule. - - Adding a revision label is a backwards-compatible version - change. Changing or removing an existing revision label in - the revision history is a non-backwards-compatible version - change, because it could impact any references to that - revision label."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 3.3, Revision label"; - } - - extension revision-label-scheme { - argument revision-label-scheme-base; - description - "The revision label scheme specifies which revision label scheme - the module or submodule uses. - - The mandatory revision-label-scheme-base argument MUST be an - identity derived from revision-label-scheme-base. - - This extension is only valid as a top-level statement, i.e., - given as as a substatement to 'module' or 'submodule'. No - substatements for this extension have been standardized. - - This extension MUST be used if there is a revision label - statement in the module or submodule. - - Adding a revision label scheme is a backwards-compatible version - change. Changing a revision label scheme is a - non-backwards-compatible version change, unless the new revision - label scheme is backwards-compatible with the replaced revision - label scheme. Removing a revision label scheme is a - non-backwards-compatible version change."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 3.3.1, Revision label scheme extension statement"; - } - - extension recommended-min { - argument revision-date-or-label; + extension recommended-min-date { + argument revision-date; description "Recommends the revision of the module that may be imported to one that matches or is derived from the specified @@ -887,28 +723,12 @@ module ietf-yang-revisions { statement with a matching revision date or revision label. Adding, removing or updating a 'recommended-min' - statement to an import is a backwards-compatible change. - "; + statement to an import is a backwards-compatible change."; reference "XXXX: Updated YANG Module Revision Handling; Section 4, Recommending a minimum revision for module imports"; } - - identity revision-label-scheme-base { - description - "Base identity from which all revision label schemes are - derived."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 3.3.1, Revision label scheme extension statement"; - - } - - - - } ]]> @@ -922,12 +742,6 @@ module ietf-yang-library-revisions { namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions"; prefix yl-rev; - - import ietf-yang-revisions { - prefix rev; - reference - "XXXX: Updated YANG Module Revision Handling"; - } import ietf-yang-library { prefix yanglib; @@ -992,77 +806,6 @@ module ietf-yang-library-revisions { "XXXX: Updated YANG Module Revision Handling"; } - // library 1.0 modules-state is not augmented with revision-label - - augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { - description - "Add a revision label to module information"; - leaf revision-label { - type rev:revision-label; - description - "The revision label associated with this module revision. - The label MUST match the revision label value in the specific - revision of the module loaded in this module-set."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 5.2.1, Advertising revision-label"; - } - } - - augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/" - + "yanglib:submodule" { - description - "Add a revision label to submodule information"; - leaf revision-label { - type rev:revision-label; - description - "The revision label associated with this submodule revision. - The label MUST match the revision label value in the specific - revision of the submodule included by the module loaded in - this module-set."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 5.2.1, Advertising revision-label"; - } - } - - augment "/yanglib:yang-library/yanglib:module-set/" - + "yanglib:import-only-module" { - description - "Add a revision label to module information"; - leaf revision-label { - type rev:revision-label; - description - "The revision label associated with this module revision. - The label MUST match the revision label value in the specific - revision of the module included in this module-set."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 5.2.1, Advertising revision-label"; - } - } - - augment "/yanglib:yang-library/yanglib:module-set/" - + "yanglib:import-only-module/yanglib:submodule" { - description - "Add a revision label to submodule information"; - leaf revision-label { - type rev:revision-label; - description - "The revision label associated with this submodule revision. - The label MUST match the rev:label value in the specific - revision of the submodule included by the - import-only-module loaded in this module-set."; - - reference - "XXXX: Updated YANG Module Revision Handling; - Section 5.2.1, Advertising revision-label"; - } - } - augment "/yanglib:yang-library/yanglib:schema" { description "Augmentations to the ietf-yang-library module to indicate how @@ -1135,7 +878,7 @@ module ietf-yang-library-revisions { This document does not define any new protocol or data nodes that are writable. - This document updates YANG Library with augmentations to include revision labels in the YANG library data and two boolean leafs to indicate whether status deprecated and status obsolete schema nodes are implemented by the server. These read-only augmentations do not add any new security considerations beyond those already present in . + This document updates YANG Library with augmentations to include two boolean leafs that indicate whether status deprecated and status obsolete schema nodes are implemented by the server. These read-only augmentations do not add any new security considerations beyond those already present in .