idnits 2.17.1 draft-ietf-netmod-yang-module-versioning-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 7 instances of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC6020, updated by this document, for RFC5378 checks: 2008-05-14) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 8, 2021) is 892 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 1474, but not defined == Unused Reference: 'I-D.ietf-netmod-rfc6991-bis' is defined on line 1541, but no explicit reference was found in the text == Outdated reference: A later version (-15) exists of draft-ietf-netmod-rfc6991-bis-08 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-yang-semver-04 == Outdated reference: A later version (-03) exists of draft-ietf-netmod-yang-packages-02 == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-versioning-reqs-05 Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton, Ed. 3 Internet-Draft Cisco Systems, Inc. 4 Updates: 6020,7950,8407,8525 (if R. Rahman, Ed. 5 approved) 6 Intended status: Standards Track B. Lengyel, Ed. 7 Expires: May 12, 2022 Ericsson 8 J. Clarke 9 Cisco Systems, Inc. 10 J. Sterne 11 Nokia 12 November 8, 2021 14 Updated YANG Module Revision Handling 15 draft-ietf-netmod-yang-module-versioning-05 17 Abstract 19 This document specifies a new YANG module update procedure that can 20 document when non-backwards-compatible changes have occurred during 21 the evolution of a YANG module. It extends the YANG import statement 22 with an earliest revision filter to better represent inter-module 23 dependencies. It provides guidelines for managing the lifecycle of 24 YANG modules and individual schema nodes. It provides a mechanism, 25 via the revision-label YANG extension, to specify a revision 26 identifier for YANG modules and submodules. This document updates 27 RFC 7950, RFC 6020, RFC 8407 and RFC 8525. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on May 12, 2022. 46 Copyright Notice 48 Copyright (c) 2021 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Updates to YANG RFCs . . . . . . . . . . . . . . . . . . 4 65 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 4 66 3. Refinements to YANG revision handling . . . . . . . . . . . . 5 67 3.1. Updating a YANG module with a new revision . . . . . . . 6 68 3.1.1. Backwards-compatible rules . . . . . . . . . . . . . 6 69 3.1.2. Non-backwards-compatible changes . . . . . . . . . . 7 70 3.2. non-backwards-compatible revision extension statement . . 7 71 3.3. Removing revisions from the revision history . . . . . . 7 72 3.4. Revision label . . . . . . . . . . . . . . . . . . . . . 9 73 3.4.1. File names . . . . . . . . . . . . . . . . . . . . . 10 74 3.4.2. Revision label scheme extension statement . . . . . . 10 75 3.5. Examples for updating the YANG module revision history . 11 76 4. Import by derived revision . . . . . . . . . . . . . . . . . 13 77 4.1. Module import examples . . . . . . . . . . . . . . . . . 14 78 5. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 16 79 5.1. Resolving ambiguous module imports . . . . . . . . . . . 16 80 5.2. YANG library versioning augmentations . . . . . . . . . . 17 81 5.2.1. Advertising revision-label . . . . . . . . . . . . . 17 82 5.2.2. Reporting how deprecated and obsolete nodes are 83 handled . . . . . . . . . . . . . . . . . . . . . . . 17 84 6. Versioning of YANG instance data . . . . . . . . . . . . . . 18 85 7. Guidelines for using the YANG module update rules . . . . . . 18 86 7.1. Guidelines for YANG module authors . . . . . . . . . . . 18 87 7.1.1. Making non-backwards-compatible changes to a YANG 88 module . . . . . . . . . . . . . . . . . . . . . . . 19 89 7.2. Versioning Considerations for Clients . . . . . . . . . . 21 90 8. Module Versioning Extension YANG Modules . . . . . . . . . . 21 91 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 30 92 10. Security Considerations . . . . . . . . . . . . . . . . . . . 31 93 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 94 11.1. YANG Module Registrations . . . . . . . . . . . . . . . 31 95 11.2. Guidance for versioning in IANA maintained YANG modules 32 96 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 97 12.1. Normative References . . . . . . . . . . . . . . . . . . 33 98 12.2. Informative References . . . . . . . . . . . . . . . . . 34 99 Appendix A. Examples of changes that are NBC . . . . . . . . . . 36 100 Appendix B. Examples of applying the NBC change guidelines . . . 36 101 B.1. Removing a data node . . . . . . . . . . . . . . . . . . 36 102 B.2. Changing the type of a leaf node . . . . . . . . . . . . 37 103 B.3. Reducing the range of a leaf node . . . . . . . . . . . . 38 104 B.4. Changing the key of a list . . . . . . . . . . . . . . . 38 105 B.5. Renaming a node . . . . . . . . . . . . . . . . . . . . . 39 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 108 1. Introduction 110 This document defines the foundational pieces of a solution to the 111 YANG module lifecycle problems described in 112 [I-D.ietf-netmod-yang-versioning-reqs]. Complementary documents 113 provide other parts of the solution, with the overall relationship of 114 the solution drafts described in [I-D.ietf-netmod-yang-solutions]. 116 Specifically, this document recognises a need (within standards 117 organizations, vendors, and the industry) to sometimes allow YANG 118 modules to evolve with non-backwards-compatible changes, which could 119 cause breakage to clients and importing YANG modules. Accepting that 120 non-backwards-compatible changes do sometimes occur, it is important 121 to have mechanisms to report where these changes occur, and to manage 122 their effect on clients and the broader YANG ecosystem. 124 The document comprises five parts: 126 Refinements to the YANG 1.1 module revision update procedure, 127 supported by new extension statements to indicate when a revision 128 contains non-backwards-compatible changes, and an optional 129 revision label. 131 A YANG extension statement allowing YANG module imports to specify 132 an earliest module revision that may satisfy the import 133 dependency. 135 Updates and augmentations to ietf-yang-library to include the 136 revision label in the module and submodule descriptions, to report 137 how "deprecated" and "obsolete" nodes are handled by a server, and 138 to clarify how module imports are resolved when multiple revisions 139 could otherwise be chosen. 141 Considerations of how versioning applies to YANG instance data. 143 Guidelines for how the YANG module update rules defined in this 144 document should be used, along with examples. 146 Note to RFC Editor (To be removed by RFC Editor) 148 Open issues are tracked at . 151 1.1. Updates to YANG RFCs 153 This document updates [RFC7950] section 11 and [RFC6020] section 10. 154 Section 3 describes modifications to YANG revision handling and 155 update rules, and Section 4 describes a YANG extension statement to 156 do import by derived revision. 158 This document updates [RFC7950] section 5.2 and [RFC6020] section 159 5.2. Section 3.4.1 describes the use of a revision label in the name 160 of a file containing a YANG module or submodule. 162 This document updates [RFC7950] section 5.6.5 and [RFC8525]. 163 Section 5.1 defines how a client of a YANG library datastore schema 164 resolves ambiguous imports for modules which are not "import-only". 166 This document updates [RFC8407] section 4.7. Section 7 provides 167 guidelines on managing the lifecycle of YANG modules that may contain 168 non-backwards-compatible changes and a branched revision history. 170 This document updates [RFC8525] with augmentations to include 171 revision labels in the YANG library data and two boolean leafs to 172 indicate whether status deprecated and status obsolete schema nodes 173 are implemented by the server. 175 2. Terminology and Conventions 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in BCP 180 14 [RFC2119] [RFC8174] when, and only when, they appear in all 181 capitals, as shown here. 183 In addition, this document uses the following terminology: 185 o YANG module revision: An instance of a YANG module, uniquely 186 identified with a revision date, with no implied ordering or 187 backwards compatibility between different revisions of the same 188 module. 190 o Backwards-compatible (BC) change: A backwards-compatible change 191 between two YANG module revisions, as defined in Section 3.1.1 193 o Non-backwards-compatible (NBC) change: A non-backwards-compatible 194 change between two YANG module revisions, as defined in 195 Section 3.1.2 197 3. Refinements to YANG revision handling 199 [RFC7950] and [RFC6020] assume, but do not explicitly state, that the 200 revision history for a YANG module or submodule is strictly linear, 201 i.e., it is prohibited to have two independent revisions of a YANG 202 module or submodule that are both directly derived from the same 203 parent revision. 205 This document clarifies [RFC7950] and [RFC6020] to explicitly allow 206 non-linear development of YANG module and submodule revisions, so 207 that they MAY have multiple revisions that directly derive from the 208 same parent revision. As per [RFC7950] and [RFC6020], YANG module 209 and submodule revisions continue to be uniquely identified by their 210 revision date, and hence all revisions of a given module or submodule 211 MUST have unique revision dates. 213 A corollary to the above is that the relationship between two module 214 or submodule revisions cannot be determined by comparing the module 215 or submodule revision date alone, and the revision history, or 216 revision label, must also be taken into consideration. 218 A module's name and revision date identifies a specific immutable 219 definition of that module within its revision history. Hence, if a 220 module includes submodules then to ensure that the module's content 221 is uniquely defined, the module's "include" statements SHOULD use 222 "revision-date" substatements to specify the exact revision date of 223 each included submodule. When a module does not include its 224 submodules by revision-date, the revision of submodules used cannot 225 be derived from the including module. Mechanisms such as YANG 226 packages [I-D.ietf-netmod-yang-packages], and YANG library [RFC8525], 227 MAY be used to specify the exact submodule revisions used when the 228 submodule revision date is not constrained by the "include" 229 statement. 231 [RFC7950] section 11 and [RFC6020] section 10 require that all 232 updates to a YANG module are BC to the previous revision of the 233 module. This document introduces a method to indicate that an NBC 234 change has occurred between module revisions: this is done by using a 235 new "non-backwards-compatible" YANG extension statement in the module 236 revision history. 238 Two revisions of a module or submodule MAY have identical content 239 except for the revision history. This could occur, for example, if a 240 module or submodule has a branched history and identical changes are 241 applied in multiple branches. 243 3.1. Updating a YANG module with a new revision 245 This section updates [RFC7950] section 11 and [RFC6020] section 10 to 246 refine the rules for permissible changes when a new YANG module 247 revision is created. 249 Where pragmatic, updates to YANG modules SHOULD be backwards- 250 compatible, following the definition in Section 3.1.1. 252 A new module revision MAY contain NBC changes, e.g., the semantics of 253 an existing data-node definition MAY be changed in an NBC manner 254 without requiring a new data-node definition with a new identifier. 255 A YANG extension, defined in Section 3.2, is used to signal the 256 potential for incompatibility to existing module users and readers. 258 As per [RFC7950] and [RFC6020], all published revisions of a module 259 are given a new unique revision date. This applies even for module 260 revisions containing (in the module or included submodules) only 261 changes to any whitespace, formatting, comments or line endings 262 (e.g., DOS vs UNIX). 264 3.1.1. Backwards-compatible rules 266 A change between two module revisions is defined as being "backwards- 267 compatible" if the change conforms to the module update rules 268 specified in [RFC7950] section 11 and [RFC6020] section 10, updated 269 by the following rules: 271 o A "status" "deprecated" statement MAY be added, or changed from 272 "current" to "deprecated", but adding or changing "status" to 273 "obsolete" is not a backwards-compatible change. 275 o YANG schema nodes with a "status" "obsolete" substatement MAY be 276 removed from published modules, and are classified as backwards- 277 compatible changes. In some circumstances it may be helpful to 278 retain the obsolete definitions since their identifiers may still 279 be referenced by other modules and to ensure that their 280 identifiers are not reused with a different meaning. 282 o In statements that have any data definition statements as 283 substatements, those data definition substatements MAY be 284 reordered, as long as they do not change the ordering of any 285 "input" or "output" data definition substatements of "rpc" or 286 "action" statements. If new data definition statements are added, 287 they can be added anywhere in the sequence of existing 288 substatements. 290 o A statement that is defined using the YANG "extension" statement 291 MAY be added, removed, or changed, if it does not change the 292 semantics of the module. Extension statement definitions SHOULD 293 specify whether adding, removing, or changing statements defined 294 by that extension are backwards-compatible or non-backwards- 295 compatible. 297 o Any changes (including whitespace or formatting changes) that do 298 not change the semantic meaning of the module are backwards 299 compatible. 301 3.1.2. Non-backwards-compatible changes 303 Any changes to YANG modules that are not defined by Section 3.1.1 as 304 being backwards-compatible are classified as "non-backwards- 305 compatible" changes. 307 3.2. non-backwards-compatible revision extension statement 309 The "rev:non-backwards-compatible" extension statement is used to 310 indicate YANG module revisions that contain NBC changes. 312 If a revision of a YANG module contains changes, relative to the 313 preceding revision in the revision history, that do not conform to 314 the module update rules defined in Section 3.1.1, then a "rev:non- 315 backwards-compatible" extension statement MUST be added as a 316 substatement to the "revision" statement. 318 3.3. Removing revisions from the revision history 320 Authors may wish to remove revision statements from a module or 321 submodule. Removal of revision information may be desirable for a 322 number of reasons including reducing the size of a large revision 323 history, or removing a revision that should no longer be used or 324 imported. Removing revision statements is allowed, but can cause 325 issues and SHOULD NOT be done without careful analysis of the 326 potential impact to users of the module or submodule. Doing so can 327 lead to import breakages when import by revision-or-derived is used. 328 Moreover, truncating history may cause loss of visibility of when 329 non-backwards-compatible changes were introduced. 331 An author MAY remove a contiguous sequence of entries from the end 332 (i.e., oldest entries) of the revision history. This is acceptable 333 even if the first remaining (oldest) revision entry in the revision 334 history contains a rev:non-backwards-compatible substatement. 336 An author MAY remove a contiguous sequence of entries in the revision 337 history as long as the presence or absence of any existing rev:non- 338 backwards-compatible substatements on all remaining entries still 339 accurately reflect the compatibility relationship to their preceding 340 entries remaining in the revision history. 342 The author MUST NOT remove the first (i.e., newest) revision entry in 343 the revision history. 345 Example revision history: 347 revision 2020-11-11 { 348 rev:revision-label 4.0.0; 349 rev:non-backwards-compatible; 350 } 352 revision 2020-08-09 { 353 rev:revision-label 3.0.0; 354 rev:non-backwards-compatible; 355 } 357 revision 2020-06-07 { 358 rev:revision-label 2.1.0; 359 } 361 revision 2020-02-10 { 362 rev:revision-label 2.0.0; 363 rev:non-backwards-compatible; 364 } 366 revision 2019-10-21 { 367 rev:revision-label 1.1.3; 368 } 370 revision 2019-03-04 { 371 rev:revision-label 1.1.2; 372 } 374 revision 2019-01-02 { 375 rev:revision-label 1.1.1; 376 } 378 In the revision history example above, removing the revision history 379 entry for 2020-02-10 would also remove the rev:non-backwards- 380 compatible annotation and hence the resulting revision history would 381 incorrectly indicate that revision 2020-06-07 is backwards-compatible 382 with revisions 2019-01-02 through 2019-10-21 when it is not, and so 383 this change cannot be made. Conversely, removing one or more 384 revisions out of 2019-03-04, 2019-10-21 and 2020-08-09 from the 385 revision history would still retain a consistent revision history, 386 and is acceptable, subject to an awareness of the concerns raised in 387 the first paragraph of this section. 389 3.4. Revision label 391 Each revision entry in a module or submodule MAY have a revision 392 label associated with it, providing an alternative alias to identify 393 a particular revision of a module or submodule. The revision label 394 could be used to provide an additional versioning identifier 395 associated with the revision. 397 A revision label scheme is a set of rules describing how a particular 398 type of revision-label operates for versioning YANG modules and 399 submodules. For example, YANG Semver [I-D.ietf-netmod-yang-semver] 400 defines a revision label scheme based on Semver 2.0.0 [semver]. 401 Other documents may define other YANG revision label schemes. 403 Submodules MAY use a revision label scheme. When they use a revision 404 label scheme, submodules MAY use a revision label scheme that is 405 different from the one used in the including module. 407 The revision label space of submodules is separate from the revision 408 label space of the including module. A change in one submodule MUST 409 result in a new revision label of that submodule and the including 410 module, but the actual values of the revision labels in the module 411 and submodule could be completely different. A change in one 412 submodule does not result in a new revision label in another 413 submodule. A change in a module revision label does not necessarily 414 mean a change to the revision label in all included submodules. 416 If a revision has an associated revision label, then it may be used 417 instead of the revision date in a "rev:revision-or-derived" extension 418 statement argument. 420 A specific revision-label identifies a specific revision of the 421 module. If two YANG modules contain the same module name and the 422 same revision-label (and hence also the same revision-date) in their 423 latest revision statement, then the file contents of the two modules, 424 including the revision history, MUST be identical. 426 3.4.1. File names 428 This section updates [RFC7950] section 5.2 and [RFC6020] section 5.2. 430 If a revision has an associated revision label, then the revision- 431 label MAY be used instead of the revision date in the filename of a 432 YANG file, where it takes the form: 434 module-or-submodule-name [['@' revision-date]|['#' revision-label]] 435 ( '.yang' / '.yin' ) 437 E.g., acme-router-module@2018-01-25.yang 438 E.g., acme-router-module#2.0.3.yang 440 YANG module (or submodule) files MAY be identified using either 441 revision-date or revision-label. Typically, only one file name 442 SHOULD exist for the same module (or submodule) revision. Two file 443 names, one with the revision date and another with the revision 444 label, MAY exist for the same module (or submodule) revision, e.g., 445 when migrating from one scheme to the other. 447 3.4.2. Revision label scheme extension statement 449 The optional "rev:revision-label-scheme" extension statement is used 450 to indicate which revision-label scheme a module or submodule uses. 451 There MUST NOT be more than one revision label scheme in a module or 452 submodule. The mandatory argument to this extension statement: 454 o specifies the revision-label scheme used by the module or 455 submodule 457 o is defined in the document which specifies the revision-label 458 scheme 460 o MUST be an identity derived from "revision-label-scheme-base". 462 The revision-label scheme used by a module or submodule SHOULD NOT 463 change during the lifetime of the module or submodule. If the 464 revision-label scheme used by a module or submodule is changed to a 465 new scheme, then all revision-label statements that do not conform to 466 the new scheme MUST be replaced or removed. 468 3.5. Examples for updating the YANG module revision history 470 The following diagram, explanation, and module history illustrates 471 how the branched revision history, "non-backwards-compatible" 472 extension statement, and "revision-label" extension statement could 473 be used: 475 Example YANG module with branched revision history. 477 Module revision date Revision label 478 2019-01-01 <- 1.0.0 479 | 480 2019-02-01 <- 2.0.0 481 | \ 482 2019-03-01 \ <- 3.0.0 483 | \ 484 | 2019-04-01 <- 2.1.0 485 | | 486 | 2019-05-01 <- 2.2.0 487 | 488 2019-06-01 <- 3.1.0 490 The tree diagram above illustrates how an example module's revision 491 history might evolve, over time. For example, the tree might 492 represent the following changes, listed in chronological order from 493 the oldest revision to the newest revision: 495 Example module, revision 2019-06-01: 497 module example-module { 499 namespace "urn:example:module"; 500 prefix "prefix-name"; 501 rev:revision-label-scheme "yangver:yang-semver"; 503 import ietf-yang-revisions { prefix "rev"; } 504 import ietf-yang-semver { prefix "yangver"; } 506 description 507 "to be completed"; 509 revision 2019-06-01 { 510 rev:revision-label 3.1.0; 511 description "Add new functionality."; 512 } 514 revision 2019-03-01 { 515 rev:revision-label 3.0.0; 516 rev:non-backwards-compatible; 517 description 518 "Add new functionality. Remove some deprecated nodes."; 519 } 521 revision 2019-02-01 { 522 rev:revision-label 2.0.0; 523 rev:non-backwards-compatible; 524 description "Apply bugfix to pattern statement"; 525 } 527 revision 2019-01-01 { 528 rev:revision-label 1.0.0; 529 description "Initial revision"; 530 } 532 //YANG module definition starts here 533 } 535 Example module, revision 2019-05-01: 537 module example-module { 539 namespace "urn:example:module"; 540 prefix "prefix-name"; 541 rev:revision-label-scheme "yangver:yang-semver"; 543 import ietf-yang-revisions { prefix "rev"; } 544 import ietf-yang-semver { prefix "yangver"; } 546 description 547 "to be completed"; 549 revision 2019-05-01 { 550 rev:revision-label 2.2.0; 551 description "Backwards-compatible bugfix to enhancement."; 552 } 554 revision 2019-04-01 { 555 rev:revision-label 2.1.0; 556 description "Apply enhancement to older release train."; 557 } 559 revision 2019-02-01 { 560 rev:revision-label 2.0.0; 561 rev:non-backwards-compatible; 562 description "Apply bugfix to pattern statement"; 563 } 565 revision 2019-01-01 { 566 rev:revision-label 1.0.0; 567 description "Initial revision"; 568 } 570 //YANG module definition starts here 571 } 573 4. Import by derived revision 575 [RFC7950] and [RFC6020] allow YANG module "import" statements to 576 optionally require the imported module to have a particular revision 577 date. In practice, importing a module with an exact revision date is 578 often too restrictive because it requires the importing module to be 579 updated whenever any change to the imported module occurs. The 580 alternative choice of using an import statement without any revision 581 date statement is also not ideal because the importing module may not 582 work with all possible revisions of the imported module. 584 Instead, it is desirable for an importing module to specify a 585 "minimum required revision" of a module that it is compatible with, 586 based on the assumption that later revisions derived from that 587 "minimum required revision" are also likely to be compatible. Many 588 possible changes to a YANG module do not break importing modules, 589 even if the changes themselves are not strictly backwards-compatible. 590 E.g., fixing an incorrect pattern statement or description for a leaf 591 would not break an import, changing the name of a leaf could break an 592 import but frequently would not, but removing a container would break 593 imports if that container is augmented by another module. 595 The ietf-revisions module defines the "revision-or-derived" extension 596 statement, a substatement to the YANG "import" statement, to allow 597 for a "minimum required revision" to be specified during import: 599 The argument to the "revision-or-derived" extension statement is a 600 revision date or a revision label. 602 A particular revision of an imported module satisfies an import's 603 "revision-or-derived" extension statement if the imported module's 604 revision history contains a revision statement with a matching 605 revision date or revision label. 607 An "import" statement MUST NOT contain both a "revision-or- 608 derived" extension statement and a "revision-date" statement. 610 The "revision-or-derived" extension statement MAY be specified 611 multiple times, allowing the import to use any module revision 612 that satisfies at least one of the "revision-or-derived" extension 613 statements. 615 The "revision-or-derived" extension statement does not guarantee 616 that all module revisions that satisfy an import statement are 617 necessarily compatible; it only gives an indication that the 618 revisions are more likely to be compatible. Hence, NBC changes to 619 an imported module may also require new revisions of any importing 620 modules, updated to accommodation those changes, along with 621 updated import "revision-or-derived" extension statements to 622 depend on the updated imported module revision. 624 Adding, modifying or removing a "revision-or-derived" extension 625 statement is considered to be a BC change. 627 4.1. Module import examples 629 Consider the example module "example-module" from Section 3.5 that is 630 hypothetically available in the following revision/label pairings: 631 2019-01-01/1.0.0, 2019-02-01/2.0.0, 2019-03-01/3.0.0, 632 2019-04-01/2.1.0, 2019-05-01/2.2.0 and 2019-06-01/3.1.0. The 633 relationship between the revisions is as before: 635 Module revision date Revision label 636 2019-01-01 <- 1.0.0 637 | 638 2019-02-01 <- 2.0.0 639 | \ 640 2019-03-01 \ <- 3.0.0 641 | \ 642 | 2019-04-01 <- 2.1.0 643 | | 644 | 2019-05-01 <- 2.2.0 645 | 646 2019-06-01 <- 3.1.0 648 4.1.1. Example 1 650 This example selects module revisions that match, or are derived from 651 the revision 2019-02-01. E.g., this dependency might be used if 652 there was a new container added in revision 2019-02-01 that is 653 augmented by the importing module. It includes revisions/labels: 654 2019-02-01/2.0.0, 2019-03-01/3.0.0, 2019-04-01/2.1.0, 655 2019-05-01/2.2.0 and 2019-06-01/3.1.0. 657 import example-module { 658 rev:revision-or-derived 2019-02-01; 659 } 661 Alternatively, the first example could have used the revision label 662 "2.0.0" instead, which selects the same set of revisions/labels. 664 import example-module { 665 rev:revision-or-derived 2.0.0; 666 } 668 4.1.2. Example 2 670 This example selects module revisions that are derived from 671 2019-04-01 by using the revision label 2.1.0. It includes revisions/ 672 labels: 2019-04-01/2.1.0 and 2019-05-01/2.2.0. Even though 673 2019-06-01/3.1.0 has a higher revision label number than 674 2019-04-01/2.1.0 it is not a derived revision, and hence it is not a 675 valid revision for import. 677 import example-module { 678 rev:revision-or-derived 2.1.0; 679 } 681 4.1.3. Example 3 683 This example selects revisions derived from either 2019-04-01 or 684 2019-06-01. It includes revisions/labels: 2019-04-01/2.1.0, 685 2019-05-01/2.2.0, and 2019-06-01/3.1.0. 687 import example-module { 688 rev:revision-or-derived 2019-04-01; 689 rev:revision-or-derived 2019-06-01; 690 } 692 5. Updates to ietf-yang-library 694 This document updates YANG 1.1 [RFC7950] and YANG library [RFC8525] 695 to clarify how ambiguous module imports are resolved. It also 696 defines the YANG module, ietf-yang-library-revisions, that augments 697 YANG library [RFC8525] with revision labels and two leafs to indicate 698 how a server implements deprecated and obsolete schema nodes. 700 5.1. Resolving ambiguous module imports 702 A YANG datastore schema, defined in [RFC8525], can specify multiple 703 revisions of a YANG module in the schema using the "import-only" 704 list, with the requirement from [RFC7950] section 5.6.5 that only a 705 single revision of a YANG module may be implemented. 707 If a YANG module import statement does not specify a specific 708 revision within the datastore schema then it could be ambiguous as to 709 which module revision the import statement should resolve to. Hence, 710 a datastore schema constructed by a client using the information 711 contained in YANG library may not exactly match the datastore schema 712 actually used by the server. 714 The following two rules remove the ambiguity: 716 If a module import statement could resolve to more than one module 717 revision defined in the datastore schema, and one of those revisions 718 is implemented (i.e., not an "import-only" module), then the import 719 statement MUST resolve to the revision of the module that is defined 720 as being implemented by the datastore schema. 722 If a module import statement could resolve to more than one module 723 revision defined in the datastore schema, and none of those revisions 724 are implemented, then the import MUST resolve to the module revision 725 with the latest revision date. 727 5.2. YANG library versioning augmentations 729 The "ietf-yang-library-revisions" YANG module has the following 730 structure (using the notation defined in [RFC8340]): 732 module: ietf-yang-library-revisions 733 augment /yanglib:yang-library/yanglib:module-set/yanglib:module: 734 +--ro revision-label? rev:revision-label 735 augment /yanglib:yang-library/yanglib:module-set/yanglib:module 736 /yanglib:submodule: 737 +--ro revision-label? rev:revision-label 738 augment /yanglib:yang-library/yanglib:module-set 739 /yanglib:import-only-module/yanglib:submodule: 740 +--ro revision-label? rev:revision-label 741 augment /yanglib:yang-library/yanglib:schema: 742 +--ro deprecated-nodes-implemented? boolean 743 +--ro obsolete-nodes-absent? boolean 745 5.2.1. Advertising revision-label 747 The ietf-yang-library-revisions YANG module augments the "module" and 748 "submodule" lists in ietf-yang-library with "revision-label" leafs to 749 optionally declare the revision label associated with each module and 750 submodule. 752 5.2.2. Reporting how deprecated and obsolete nodes are handled 754 The ietf-yang-library-revisions YANG module augments YANG library 755 with two boolean leafs to allow a server to report how it implements 756 status "deprecated" and status "obsolete" schema nodes. The leafs 757 are: 759 deprecated-nodes-implemented: If set to "true", this leaf indicates 760 that all schema nodes with a status "deprecated" are implemented 761 equivalently as if they had status "current"; otherwise deviations 762 MUST be used to explicitly remove "deprecated" nodes from the 763 schema. If this leaf is set to "false" or absent, then the 764 behavior is unspecified. 766 obsolete-nodes-absent: If set to "true", this leaf indicates that 767 the server does not implement any status "obsolete" schema nodes. 768 If this leaf is set to "false" or absent, then the behaviour is 769 unspecified. 771 Servers SHOULD set both the "deprecated-nodes-implemented" and 772 "obsolete-nodes-absent" leafs to "true". 774 If a server does not set the "deprecated-nodes-implemented" leaf to 775 "true", then clients MUST NOT rely solely on the "rev:non-backwards- 776 compatible" statements to determine whether two module revisions are 777 backwards-compatible, and MUST also consider whether the status of 778 any nodes has changed to "deprecated" and whether those nodes are 779 implemented by the server. 781 6. Versioning of YANG instance data 783 Instance data sets [I-D.ietf-netmod-yang-instance-file-format] do not 784 directly make use of the updated revision handling rules described in 785 this document, as compatibility for instance data is undefined. 787 However, instance data specifies the content-schema of the data-set. 788 This schema SHOULD make use of versioning using revision dates and/or 789 revision labels for the individual YANG modules that comprise the 790 schema or potentially for the entire schema itself (e.g., 791 [I-D.ietf-netmod-yang-packages]). 793 In this way, the versioning of a content-schema associated with an 794 instance data set may help a client to determine whether the instance 795 data could also be used in conjunction with other revisions of the 796 YANG schema, or other revisions of the modules that define the 797 schema. 799 7. Guidelines for using the YANG module update rules 801 The following text updates section 4.7 of [RFC8407] to revise the 802 guidelines for updating YANG modules. 804 7.1. Guidelines for YANG module authors 806 All IETF YANG modules MUST include revision-label statements for all 807 newly published YANG modules, and all newly published revisions of 808 existing YANG modules. The revision-label MUST take the form of a 809 YANG semantic version number [I-D.ietf-netmod-yang-semver]. 811 NBC changes to YANG modules may cause problems to clients, who are 812 consumers of YANG models, and hence YANG module authors SHOULD 813 minimize NBC changes and keep changes BC whenever possible. 815 When NBC changes are introduced, consideration should be given to the 816 impact on clients and YANG module authors SHOULD try to mitigate that 817 impact. 819 A "rev:non-backwards-compatible" statement MUST be added if there are 820 NBC changes relative to the previous revision. 822 Removing old revision statements from a module's revision history 823 could break import by revision, and hence it is RECOMMENDED to retain 824 them. If all dependencies have been updated to not import specific 825 revisions of a module, then the corresponding revision statements can 826 be removed from that module. An alternative solution, if the 827 revision section is too long, would be to remove, or curtail, the 828 older description statements associated with the previous revisions. 830 The "rev:revision-or-derived" extension SHOULD be used in YANG module 831 imports to indicate revision dependencies between modules in 832 preference to the "revision-date" statement, which causes overly 833 strict import dependencies and SHOULD NOT be used. 835 A module that includes submodules SHOULD use the "revision-date" 836 statement to include specific submodule revisions. The revision of 837 the including module MUST be updated when any included submodule has 838 changed. 840 In some cases a module or submodule revision that is not strictly NBC 841 by the definition in Section 3.1.2 of this specification may include 842 the "non-backwards-compatible" statement. Here is an example when 843 adding the statement may be desirable: 845 o A "config false" leaf had its value space expanded (for example, a 846 range was increased, or additional enum values were added) and the 847 author or server implementor feels there is a significant 848 compatibility impact for clients and users of the module or 849 submodule 851 7.1.1. Making non-backwards-compatible changes to a YANG module 853 There are various valid situations where a YANG module has to be 854 modified in an NBC way. Here are the different ways in which this 855 can be done: 857 o NBC changes can be sometimes be done incrementally using the 858 "deprecated" status to provide clients time to adapt to NBC 859 changes. 861 o NBC changes are done at once, i.e. without using "status" 862 statements. Depending on the change, this may have a big impact 863 on clients. 865 o If the server can support multiple revisions of the YANG module or 866 of YANG packages (as specified in 867 [I-D.ietf-netmod-yang-packages]), and allows the client to select 868 the revision (as per [I-D.ietf-netmod-yang-ver-selection]), then 869 NBC changes MAY be done without using "status" statements. 871 Clients would be required to select the revision which they 872 support and the NBC change would have no impact on them. 874 Here are some guidelines on how non-backwards-compatible changes can 875 be made incrementally, with the assumption that deprecated nodes are 876 implemented by the server, and obsolete nodes are not: 878 1. The changes should be made gradually, e.g., a data node's status 879 SHOULD NOT be changed directly from "current" to "obsolete" (see 880 Section 4.7 of [RFC8407]), instead the status SHOULD first be 881 marked "deprecated". At some point in the future, when support 882 is removed for the data node, there are two options. The first, 883 and preferred, option is to keep the data node definition in the 884 model and change the status to "obsolete". The second option is 885 to simply remove the data node from the model, but this has the 886 risk of breaking modules which import the modified module, and 887 the removed identifier may be accidently reused in a future 888 revision. 890 2. For deprecated data nodes the "description" statement SHOULD also 891 indicate until when support for the node is guaranteed (if 892 known). If there is a replacement data node, rpc, action or 893 notification for the deprecated node, this SHOULD be stated in 894 the "description". The reason for deprecating the node can also 895 be included in the "description" if it is deemed to be of 896 potential interest to the user. 898 3. For obsolete data nodes, it is RECOMMENDED to keep the above 899 information, from when the node had status "deprecated", which is 900 still relevant. 902 4. When obsoleting or deprecating data nodes, the "deprecated" or 903 "obsolete" status SHOULD be applied at the highest possible level 904 in the data tree. For clarity, the "status" statement SHOULD 905 also be applied to all descendent data nodes, but the additional 906 status related information does not need to be repeated if it 907 does not introduce any additional information. 909 5. NBC changes which can break imports SHOULD be avoided because of 910 the impact on the importing module. The importing modules could 911 get broken, e.g., if an augmented node in the importing module 912 has been removed from the imported module. Alternatively, the 913 schema of the importing modules could undergo an NBC change due 914 to the NBC change in the imported module, e.g., if a node in a 915 grouping has been removed. As described in Appendix B.1, instead 916 of removing a node, that node SHOULD first be deprecated and then 917 obsoleted. 919 See Appendix B for examples on how NBC changes can be made. 921 7.2. Versioning Considerations for Clients 923 Guidelines for clients of modules using the new module revision 924 update procedure: 926 o Clients SHOULD be liberal when processing data received from a 927 server. For example, the server may have increased the range of 928 an operational node causing the client to receive a value which is 929 outside the range of the YANG model revision it was coded against. 931 o Clients SHOULD monitor changes to published YANG modules through 932 their revision history, and use appropriate tooling to understand 933 the specific changes between module revision. In particular, 934 clients SHOULD NOT migrate to NBC revisions of a module without 935 understanding any potential impact of the specific NBC changes. 937 o Clients SHOULD plan to make changes to match published status 938 changes. When a node's status changes from "current" to 939 "deprecated", clients SHOULD plan to stop using that node in a 940 timely fashion. When a node's status changes to "obsolete", 941 clients MUST stop using that node. 943 8. Module Versioning Extension YANG Modules 945 YANG module with extension statements for annotating NBC changes, 946 revision label, revision label scheme, and importing by revision. 948 file "ietf-yang-revisions@2021-11-04.yang" 949 module ietf-yang-revisions { 950 yang-version 1.1; 951 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions"; 952 prefix rev; 954 // RFC Ed.: We need the bis version to get the new type revision-identifier 955 // If 6991-bis is not yet an RFC we need to copy the definition here 956 import ietf-yang-types { 957 prefix yang; 958 reference 959 "XXXX [ietf-netmod-rfc6991-bis]: Common YANG Data Types"; 960 } 962 organization 963 "IETF NETMOD (Network Modeling) Working Group"; 964 contact 965 "WG Web: 966 WG List: 967 Author: Joe Clarke 968 970 Author: Reshad Rahman 971 973 Author: Robert Wilton 974 976 Author: Balazs Lengyel 977 979 Author: Jason Sterne 980 "; 981 description 982 "This YANG 1.1 module contains definitions and extensions to 983 support updated YANG revision handling. 985 Copyright (c) 2021 IETF Trust and the persons identified as 986 authors of the code. All rights reserved. 988 Redistribution and use in source and binary forms, with or 989 without modification, is permitted pursuant to, and subject 990 to the license terms contained in, the Simplified BSD License 991 set forth in Section 4.c of the IETF Trust's Legal Provisions 992 Relating to IETF Documents 993 (http://trustee.ietf.org/license-info). 995 This version of this YANG module is part of RFC XXXX; see 996 the RFC itself for full legal notices. 998 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 999 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1000 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1001 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1002 they appear in all capitals, as shown here."; 1004 // RFC Ed.: update the date below with the date of RFC publication 1005 // and remove this note. 1006 // RFC Ed.: replace XXXX (inc above) with actual RFC number and 1007 // remove this note. 1009 revision 2021-11-04 { 1010 rev:revision-label 1.0.0-draft-ietf-netmod-yang-module-versioning-05; 1011 description 1012 "Initial version."; 1013 reference 1014 "XXXX: Updated YANG Module Revision Handling"; 1016 } 1018 typedef revision-label { 1019 type string { 1020 length "1..255"; 1021 pattern '[a-zA-Z0-9,\-_.+]+'; 1022 pattern '\d{4}-\d{2}-\d{2}' { 1023 modifier invert-match; 1024 } 1025 } 1026 description 1027 "A label associated with a YANG revision. 1029 Alphanumeric characters, comma, hyphen, underscore, period 1030 and plus are the only accepted characters. MUST NOT match 1031 revision-date."; 1032 reference 1033 "XXXX: Updated YANG Module Revision Handling; 1034 Section 3.3, Revision label"; 1035 } 1037 typedef revision-date-or-label { 1038 type union { 1039 type yang:revision-identifier; 1040 type revision-label; 1041 } 1042 description 1043 "Represents either a YANG revision date or a revision label"; 1044 } 1046 extension non-backwards-compatible { 1047 description 1048 "This statement is used to indicate YANG module revisions that 1049 contain non-backwards-compatible changes. 1051 The statement MUST only be a substatement of the 'revision' 1052 statement. Zero or one 'non-backwards-compatible' statements 1053 per parent statement is allowed. No substatements for this 1054 extension have been standardized. 1056 If a revision of a YANG module contains changes, relative to 1057 the preceding revision in the revision history, that do not 1058 conform to the backwards compatible module update rules defined 1059 in RFC-XXX, then the 'non-backwards-compatible' statement MUST 1060 be added as a substatement to the revision statement. 1062 Conversely, if a revision does not contain a 1063 'non-backwards-compatible' statement then all changes, 1064 relative to the preceding revision in the revision history, 1065 MUST be backwards-compatible. 1067 A new module revision that only contains changes that are 1068 backwards compatible SHOULD NOT include the 1069 'non-backwards-compatible' statement. An example of when 1070 an author might add the 'non-backwards-compatible' statement 1071 is if they believe a change could negatively impact clients 1072 even though the backwards compatibility rules defined in 1073 RFC-XXXX classify it as a backwards-compatible change. 1075 Add, removing, or changing a 'non-backwards-compatible' 1076 statement is a backwards-compatible version change."; 1078 reference 1079 "XXXX: Updated YANG Module Revision Handling; 1080 Section 3.2, non-backwards-compatible revision extension statement"; 1081 } 1083 extension revision-label { 1084 argument revision-label; 1085 description 1086 "The revision label can be used to provide an additional 1087 versioning identifier associated with a module or submodule 1088 revision. One such scheme that 1089 could be used is [XXXX: ietf-netmod-yang-semver]. 1091 The format of the revision-label argument MUST conform to the 1092 pattern defined for the revision-label typedef in this module. 1094 The statement MUST only be a substatement of the revision 1095 statement. Zero or one revision-label statements per parent 1096 statement are allowed. No substatements for this extension 1097 have been standardized. 1099 Revision labels MUST be unique amongst all revisions of a 1100 module or submodule. 1102 Adding a revision label is a backwards-compatible version 1103 change. Changing or removing an existing revision label in 1104 the revision history is a non-backwards-compatible version 1105 change, because it could impact any references to that 1106 revision label."; 1108 reference 1109 "XXXX: Updated YANG Module Revision Handling; 1110 Section 3.3, Revision label"; 1111 } 1112 extension revision-label-scheme { 1113 argument revision-label-scheme-base; 1114 description 1115 "The revision label scheme specifies which revision-label scheme 1116 the module or submodule uses. 1118 The mandatory revision-label-scheme-base argument MUST be an 1119 identity derived from revision-label-scheme-base. 1121 This extension is only valid as a top-level statement, i.e., 1122 given as as a substatement to 'module' or 'submodule'. No 1123 substatements for this extension have been standardized. 1125 This extension MUST be used if there is a revision-label 1126 statement in the module or submodule. 1128 Adding a revision label scheme is a backwards-compatible version 1129 change. Changing a revision label scheme is a 1130 non-backwards-compatible version change, unless the new revision 1131 label scheme is backwards-compatible with the replaced revision 1132 label scheme. Removing a revision label scheme is a 1133 non-backwards-compatible version change."; 1135 reference 1136 "XXXX: Updated YANG Module Revision Handling; 1137 Section 3.3.1, Revision label scheme extension statement"; 1138 } 1140 extension revision-or-derived { 1141 argument revision-date-or-label; 1142 description 1143 "Restricts the revision of the module that may be imported to 1144 one that matches or is derived from the specified 1145 revision-date or revision-label. 1147 The argument value MUST conform to the 1148 'revision-date-or-label' defined type. 1150 The statement MUST only be a substatement of the import 1151 statement. Zero, one or more 'revision-or-derived' statements 1152 per parent statement are allowed. No substatements for this 1153 extension have been standardized. 1155 If specified multiple times, then any module revision that 1156 satisfies at least one of the 'revision-or-derived' statements 1157 is an acceptable revision for import. 1159 An 'import' statement MUST NOT contain both a 1160 'revision-or-derived' extension statement and a 1161 'revision-date' statement. 1163 A particular revision of an imported module satisfies an 1164 import's 'revision-or-derived' extension statement if the 1165 imported module's revision history contains a revision 1166 statement with a matching revision date or revision label. 1168 The 'revision-or-derived' extension statement does not 1169 guarantee that all module revisions that satisfy an import 1170 statement are necessarily compatible, it only gives an 1171 indication that the revisions are more likely to be 1172 compatible. 1174 Adding, removing or updating a 'revision-or-derived' 1175 statement to an import is a backwards-compatible change. 1176 "; 1178 reference 1179 "XXXX: Updated YANG Module Revision Handling; 1180 Section 4, Import by derived revision"; 1181 } 1183 identity revision-label-scheme-base { 1184 description 1185 "Base identity from which all revision label schemes are 1186 derived."; 1188 reference 1189 "XXXX: Updated YANG Module Revision Handling; 1190 Section 3.3.1, Revision label scheme extension statement"; 1192 } 1193 } 1194 1196 YANG module with augmentations to YANG Library to revision labels 1198 file "ietf-yang-library-revisions@2021-11-04.yang" 1199 module ietf-yang-library-revisions { 1200 yang-version 1.1; 1201 namespace 1202 "urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions"; 1203 prefix yl-rev; 1205 import ietf-yang-revisions { 1206 prefix rev; 1207 reference 1208 "XXXX: Updated YANG Module Revision Handling"; 1209 } 1211 import ietf-yang-library { 1212 prefix yanglib; 1213 reference "RFC 8525: YANG Library"; 1214 } 1216 organization 1217 "IETF NETMOD (Network Modeling) Working Group"; 1218 contact 1219 "WG Web: 1220 WG List: 1222 Author: Joe Clarke 1223 1225 Author: Reshad Rahman 1226 1228 Author: Robert Wilton 1229 1231 Author: Balazs Lengyel 1232 1234 Author: Jason Sterne 1235 "; 1236 description 1237 "This module contains augmentations to YANG Library to add module 1238 level revision label and to provide an indication of how 1239 deprecated and obsolete nodes are handled by the server. 1241 Copyright (c) 2021 IETF Trust and the persons identified as 1242 authors of the code. All rights reserved. 1244 Redistribution and use in source and binary forms, with or 1245 without modification, is permitted pursuant to, and subject 1246 to the license terms contained in, the Simplified BSD License 1247 set forth in Section 4.c of the IETF Trust's Legal Provisions 1248 Relating to IETF Documents 1249 (http://trustee.ietf.org/license-info). 1251 This version of this YANG module is part of RFC XXXX; see 1252 the RFC itself for full legal notices. 1254 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1255 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1256 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1257 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1258 they appear in all capitals, as shown here."; 1260 // RFC Ed.: update the date below with the date of RFC publication 1261 // and remove this note. 1262 // RFC Ed.: replace XXXX (including in the imports above) with 1263 // actual RFC number and remove this note. 1264 // RFC Ed.: please replace revision-label version with 1.0.0 and 1265 // remove this note. 1266 revision 2021-11-04 { 1267 rev:revision-label 1.0.0-draft-ietf-netmod-yang-module-versioning-05; 1268 description 1269 "Initial revision"; 1270 reference 1271 "XXXX: Updated YANG Module Revision Handling"; 1272 } 1274 // library 1.0 modules-state is not augmented with revision-label 1276 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { 1277 description 1278 "Add a revision label to module information"; 1279 leaf revision-label { 1280 type rev:revision-label; 1281 description 1282 "The revision label associated with this module revision. 1283 The label MUST match the rev:revision-label value in the specific 1284 revision of the module loaded in this module-set."; 1286 reference 1287 "XXXX: Updated YANG Module Revision Handling; 1288 Section 5.2.1, Advertising revision-label"; 1289 } 1290 } 1292 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module/" 1293 + "yanglib:submodule" { 1294 description 1295 "Add a revision label to submodule information"; 1296 leaf revision-label { 1297 type rev:revision-label; 1298 description 1299 "The revision label associated with this submodule revision. 1300 The label MUST match the rev:revision-label value in the specific 1301 revision of the submodule included by the module loaded in 1302 this module-set."; 1304 reference 1305 "XXXX: Updated YANG Module Revision Handling; 1306 Section 5.2.1, Advertising revision-label"; 1307 } 1308 } 1310 augment "/yanglib:yang-library/yanglib:module-set/" 1311 + "yanglib:import-only-module" { 1312 description 1313 "Add a revision label to module information"; 1314 leaf revision-label { 1315 type rev:revision-label; 1316 description 1317 "The revision label associated with this module revision. 1318 The label MUST match the rev:revision-label value in the specific 1319 revision of the module included in this module-set."; 1321 reference 1322 "XXXX: Updated YANG Module Revision Handling; 1323 Section 5.2.1, Advertising revision-label"; 1324 } 1325 } 1327 augment "/yanglib:yang-library/yanglib:module-set/" 1328 + "yanglib:import-only-module/yanglib:submodule" { 1329 description 1330 "Add a revision label to submodule information"; 1331 leaf revision-label { 1332 type rev:revision-label; 1333 description 1334 "The revision label associated with this submodule revision. 1335 The label MUST match the rev:label value in the specific 1336 revision of the submodule included by the 1337 import-only-module loaded in this module-set."; 1339 reference 1340 "XXXX: Updated YANG Module Revision Handling; 1341 Section 5.2.1, Advertising revision-label"; 1342 } 1343 } 1345 augment "/yanglib:yang-library/yanglib:schema" { 1346 description 1347 "Augmentations to the ietf-yang-library module to indicate how 1348 deprecated and obsoleted nodes are handled for each datastore 1349 schema supported by the server."; 1351 leaf deprecated-nodes-implemented { 1352 type boolean; 1353 description 1354 "If set to true, this leaf indicates that all schema nodes with 1355 a status 'deprecated' are implemented 1356 equivalently as if they had status 'current'; otherwise 1357 deviations MUST be used to explicitly remove deprecated 1358 nodes from the schema. If this leaf is absent or set to false, 1359 then the behavior is unspecified."; 1361 reference 1362 "XXXX: Updated YANG Module Revision Handling; 1363 Section 5.2.2, Reporting how deprecated and obsolete nodes 1364 are handled"; 1365 } 1367 leaf obsolete-nodes-absent { 1368 type boolean; 1369 description 1370 "If set to true, this leaf indicates that the server does not 1371 implement any status 'obsolete' schema nodes. If this leaf is 1372 absent or set to false, then the behaviour is unspecified."; 1374 reference 1375 "XXXX: Updated YANG Module Revision Handling; 1376 Section 5.2.2, Reporting how deprecated and obsolete nodes 1377 are handled"; 1378 } 1379 } 1380 } 1381 1383 9. Contributors 1385 This document grew out of the YANG module versioning design team that 1386 started after IETF 101. The following individuals are (or have been) 1387 members of the design team and have worked on the YANG versioning 1388 project: 1390 o Balazs Lengyel 1392 o Benoit Claise 1394 o Bo Wu 1396 o Ebben Aries 1398 o Jan Lindblad 1399 o Jason Sterne 1401 o Joe Clarke 1403 o Juergen Schoenwaelder 1405 o Mahesh Jethanandani 1407 o Michael (Wangzitao) 1409 o Qin Wu 1411 o Reshad Rahman 1413 o Rob Wilton 1415 The initial revision of this document was refactored and built upon 1416 [I-D.clacla-netmod-yang-model-update]. We would like to thank Kevin 1417 D'Souza and Benoit Claise for their initial work in this problem 1418 space. 1420 Discussons on the use of Semver for YANG versioning has been held 1421 with authors of the OpenConfig YANG models. We would like to thank 1422 both Anees Shaikh and Rob Shakir for their input into this problem 1423 space. 1425 We would also like to thank Lou Berger, Andy Bierman, Martin 1426 Bjorklund, Italo Busi, Tom Hill, Scott Mansfield, Kent Watsen for 1427 their contributions and review comments. 1429 10. Security Considerations 1431 The document does not define any new protocol or data model. There 1432 are no security considerations beyond those specified in [RFC7950] 1433 and [RFC6020]. 1435 11. IANA Considerations 1437 11.1. YANG Module Registrations 1439 This document requests IANA to registers a URI in the "IETF XML 1440 Registry" [RFC3688]. Following the format in RFC 3688, the following 1441 registrations are requested. 1443 URI: urn:ietf:params:xml:ns:yang:ietf-yang-revisions 1444 Registrant Contact: The IESG. 1445 XML: N/A, the requested URI is an XML namespace. 1447 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library-revisions 1448 Registrant Contact: The IESG. 1449 XML: N/A, the requested URI is an XML namespace. 1451 The following YANG module is requested to be registred in the "IANA 1452 Module Names" [RFC6020]. Following the format in RFC 6020, the 1453 following registrations are requested: 1455 The ietf-yang-revisions module: 1457 Name: ietf-yang-revisions 1459 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-revisions 1461 Prefix: rev 1463 Reference: [RFCXXXX] 1465 The ietf-yang-library-revisions module: 1467 Name: ietf-yang-library-revisions 1469 XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library- 1470 revisions 1472 Prefix: yl-rev 1474 Reference: [RFCXXXX] 1476 11.2. Guidance for versioning in IANA maintained YANG modules 1478 Note for IANA (to be removed by the RFC editor): Please check that 1479 the registries and IANA YANG modules are referenced in the 1480 appropriate way. 1482 IANA is responsible for maintaining and versioning YANG modules that 1483 are derived from other IANA registries. For example, "iana-if- 1484 type.yang" [IfTypeYang] is derived from the "Interface Types (ifType) 1485 IANA registry" [IfTypesReg], and "iana-routing-types.yang" 1486 [RoutingTypesYang] is derived from the "Address Family Numbers" 1487 [AddrFamilyReg] and "Subsequent Address Family Identifiers (SAFI) 1488 Parameters" [SAFIReg] IANA registries. 1490 Normally, updates to the registries cause any derived YANG modules to 1491 be updated in a backwards-compatible way, but there are some cases 1492 where the registry updates can cause non-backward-compatible updates 1493 to the derived YANG module. An example of such an update is the 1494 2020-12-31 revision of iana-routing-types.yang 1496 [RoutingTypesDecRevision], where the enum name for two SAFI values 1497 was changed. 1499 In all cases, IANA MUST follow the versioning guidance specified in 1500 Section 3.1, and MUST include a "rev:non-backwards-compatible" 1501 substatement to the latest revision statement whenever an IANA 1502 maintained module is updated in a non-backwards-compatible way, as 1503 described in Section 3.2. 1505 Note: For published IANA maintained YANG modules that contain non- 1506 backwards-compatible changes between revisions, a new revision should 1507 be published with the "rev:non-backwards-compatible" substatement 1508 retrospectively added to any revisions containing non-backwards- 1509 compatible changes. 1511 Non-normative examples of updates to enumeration types in IANA 1512 maintained modules that would be classified as non-backwards- 1513 compatible changes are: Changing the status of an enumeration typedef 1514 to obsolete, changing the status of an enum entry to obsolete, 1515 removing an enum entry, changing the identifier of an enum entry, or 1516 changing the described meaning of an enum entry. 1518 Non-normative examples of updates to enumeration types in IANA 1519 maintained modules that would be classified as backwards-compatible 1520 changes are: Adding a new enum entry to the end of the enumeration, 1521 changing the status or an enum entry to deprecated, or improving the 1522 description of an enumeration that does not change its defined 1523 meaning. 1525 Non-normative examples of updates to identity types in IANA 1526 maintained modules that would be classified as non-backwards- 1527 compatible changes are: Changing the status of an identity to 1528 obsolete, removing an identity, renaming an identity, or changing the 1529 described meaning of an identity. 1531 Non-normative examples of updates to identity types in IANA 1532 maintained modules that would be classified as backwards-compatible 1533 changes are: Adding a new identity, changing the status or an 1534 identity to deprecated, or improving the description of an identity 1535 that does not change its defined meaning. 1537 12. References 1539 12.1. Normative References 1541 [I-D.ietf-netmod-rfc6991-bis] 1542 Schoenwaelder, J., "Common YANG Data Types", draft-ietf- 1543 netmod-rfc6991-bis-08 (work in progress), November 2021. 1545 [I-D.ietf-netmod-yang-semver] 1546 Clarke, J., Wilton, R., Rahman, R., Lengyel, B., Sterne, 1547 J., and B. Claise, "YANG Semantic Versioning", draft-ietf- 1548 netmod-yang-semver-04 (work in progress), October 2021. 1550 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1551 Requirement Levels", BCP 14, RFC 2119, 1552 DOI 10.17487/RFC2119, March 1997, 1553 . 1555 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1556 DOI 10.17487/RFC3688, January 2004, 1557 . 1559 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1560 the Network Configuration Protocol (NETCONF)", RFC 6020, 1561 DOI 10.17487/RFC6020, October 2010, 1562 . 1564 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1565 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1566 . 1568 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1569 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1570 May 2017, . 1572 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1573 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1574 DOI 10.17487/RFC8407, October 2018, 1575 . 1577 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1578 and R. Wilton, "YANG Library", RFC 8525, 1579 DOI 10.17487/RFC8525, March 2019, 1580 . 1582 12.2. Informative References 1584 [AddrFamilyReg] 1585 "Address Family Numbers IANA Registry", 1586 . 1589 [I-D.clacla-netmod-yang-model-update] 1590 Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New 1591 YANG Module Update Procedure", draft-clacla-netmod-yang- 1592 model-update-06 (work in progress), July 2018. 1594 [I-D.ietf-netmod-yang-instance-file-format] 1595 Lengyel, B. and B. Claise, "YANG Instance Data File 1596 Format", draft-ietf-netmod-yang-instance-file-format-21 1597 (work in progress), October 2021. 1599 [I-D.ietf-netmod-yang-packages] 1600 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 1601 "YANG Packages", draft-ietf-netmod-yang-packages-02 (work 1602 in progress), October 2021. 1604 [I-D.ietf-netmod-yang-solutions] 1605 Wilton, R., "YANG Versioning Solution Overview", draft- 1606 ietf-netmod-yang-solutions-01 (work in progress), November 1607 2020. 1609 [I-D.ietf-netmod-yang-ver-selection] 1610 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 1611 "YANG Schema Selection", draft-ietf-netmod-yang-ver- 1612 selection-00 (work in progress), March 2020. 1614 [I-D.ietf-netmod-yang-versioning-reqs] 1615 Clarke, J., "YANG Module Versioning Requirements", draft- 1616 ietf-netmod-yang-versioning-reqs-05 (work in progress), 1617 July 2021. 1619 [IfTypesReg] 1620 "Interface Types (ifType) IANA Registry", 1621 . 1624 [IfTypeYang] 1625 "iana-if-type YANG Module", 1626 . 1629 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1630 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1631 . 1633 [RoutingTypesDecRevision] 1634 "2020-12-31 revision of iana-routing-types.yang", 1635 . 1638 [RoutingTypesYang] 1639 "iana-routing-types YANG Module", 1640 . 1643 [SAFIReg] "Subsequent Address Family Identifiers (SAFI) Parameters 1644 IANA Registry", . 1647 [semver] "Semantic Versioning 2.0.0", . 1649 Appendix A. Examples of changes that are NBC 1651 Examples of NBC changes include: 1653 o Deleting a data node, or changing it to status obsolete. 1655 o Changing the name, type, or units of a data node. 1657 o Modifying the description in a way that changes the semantic 1658 meaning of the data node. 1660 o Any changes that change or reduce the allowed value set of the 1661 data node, either through changes in the type definition, or the 1662 addition or changes to "must" statements, or changes in the 1663 description. 1665 o Adding or modifying "when" statements that reduce when the data 1666 node is available in the schema. 1668 o Making the statement conditional on if-feature. 1670 Appendix B. Examples of applying the NBC change guidelines 1672 The following sections give steps that could be taken for making NBC 1673 changes to a YANG module or submodule using the incremental approach 1674 described in section Section 7.1.1. 1676 The examples are all for "config true" nodes. 1678 Alternatively, the NBC changes MAY be done non-incrementally and 1679 without using "status" statements if the server can support multiple 1680 revisions of the YANG module or of YANG packages. Clients would be 1681 required to select the revision which they support and the NBC change 1682 would have no impact on them. 1684 B.1. Removing a data node 1686 Removing a leaf or container from the data tree, e.g., because 1687 support for the corresponding feature is being removed: 1689 1. The schema node's status is changed to "deprecated" and the node 1690 is supported for some period of time (e.g. one year). This is a 1691 BC change. 1693 2. When the schema node is not supported anymore, its status is 1694 changed to "obsolete" and the "description" updated. This is an 1695 NBC change. 1697 B.2. Changing the type of a leaf node 1699 Changing the type of a leaf node. e.g., a "vpn-id" node of type 1700 integer being changed to a string: 1702 1. The status of schema node "vpn-id" is changed to "deprecated" and 1703 the node is supported for some period of time (e.g. one year). 1704 This is a BC change. The description is updated to indicate that 1705 "vpn-name" is replacing this node. 1707 2. A new schema node, e.g., "vpn-name", of type string is added to 1708 the same location as the existing node "vpn-id". This new node 1709 has status "current" and its description explains that it is 1710 replacing node "vpn-id". 1712 3. During the period of time when both schema nodes are supported, 1713 the interactions between the two nodes is outside the scope of 1714 this document and will vary on a case by case basis. Here are 1715 some options: 1717 1. A server may prevent the new node from being set if the old 1718 node is already set (and vice-versa). A "choice" 1719 construction could be used, or the new node may have a "when" 1720 statement to achieve this. The old node must not have a 1721 "when" statement since this would be an NBC change, but the 1722 server could reject the old node from being set if the new 1723 node is already set. 1725 2. If the new node is set and a client does a get or get-config 1726 operation on the old node, the server could map the value. 1727 For example, if the new node "vpn-name" has value "123" then 1728 the server could return integer value 123 for the old node 1729 "vpn-id". However, if the value can not be mapped then the 1730 configuration would be incomplete. The behavior in this case 1731 is outside the scope of this document. 1733 4. When the schema node "vpn-id" is not supported anymore, its 1734 status is changed to "obsolete" and the "description" is updated. 1735 This is an NBC change. 1737 B.3. Reducing the range of a leaf node 1739 Reducing the range of values of a leaf-node, e.g., consider a "vpn- 1740 id" schema node of type uint32 being changed from range 1..5000 to 1741 range 1..2000: 1743 1. If all values which are being removed were never supported, e.g., 1744 if a vpn-id of 2001 or higher was never accepted, this is a BC 1745 change for the functionality (no functionality change). Even if 1746 it is an NBC change for the YANG model, there should be no impact 1747 for clients using that YANG model. 1749 2. If one or more values being removed was previously supported, 1750 e.g., if a vpn-id of 3333 was accepted previously, this is an NBC 1751 change for the YANG model. Clients using the old YANG model will 1752 be impacted, so a change of this nature should be done carefully, 1753 e.g., by using the steps described in Appendix B.2 1755 B.4. Changing the key of a list 1757 Changing the key of a list has a big impact to the client. For 1758 example, consider a "sessions" list which has a key "interface" and 1759 there is a need to change the key to "dest-address". Such a change 1760 can be done in steps: 1762 1. The status of list "sessions" is changed to "deprecated" and the 1763 list is supported for some period of time (e.g. one year). This 1764 is a BC change. The description is updated to indicate the new 1765 list that is replacing this list. 1767 2. A new list is created in the same location with the same 1768 descendant schema nodes but with "dest-address" as key. Finding 1769 an appropriate name for the new list can be difficult. In this 1770 case the new list is called "sessions-address", has status 1771 "current" and its description should explain that it is replacing 1772 list "session". 1774 3. During the period of time when both lists are supported, the 1775 interactions between the two lists is outside the scope of this 1776 document and will vary on a case by case basis. Here are some 1777 options: 1779 1. A server could prevent entries in the new list from being 1780 created if the old list already has entries (and vice-versa). 1782 2. If the new list has entries created and a client does a get 1783 or get-config operation on the old list, the server could map 1784 the entries. However, if the new list has entries which 1785 would lead to duplicate keys in the old list, the mapping can 1786 not be done. 1788 4. When list "sessions" is not available anymore, its status is 1789 changed to "obsolete" and the "description" is updated. This is 1790 an NBC change. 1792 If the server can support NBC revisions of the YANG module 1793 simultaneously using version selection 1794 [I-D.ietf-netmod-yang-ver-selection], then the changes can be done 1795 immediately: 1797 1. The new revision of the YANG module has the list "sessions" 1798 modified to have "dest-address" as key, this is an NBC change. 1800 2. Clients which require the previous functionality select the older 1801 module revision 1803 B.5. Renaming a node 1805 A leaf or container schema node may be renamed, either due to a 1806 spelling error in the previous name or because of a better name. For 1807 example a node "ip-adress" could be renamed to "ip-address": 1809 1. The status of the existing node "ip-adress" is changed to 1810 "deprecated" and is supported for some period of time (e.g. one 1811 year). This is a BC change. The description is updated to 1812 indicate the node that is replacing this node. 1814 2. The new schema node "ip-address" is added to the same location as 1815 the existing node "ip-adress". This new node has status 1816 "current" and its description should explain that it is replacing 1817 node "ip-adress". 1819 3. During the period of time when both nodes are available, the 1820 interactions between the two nodes is outside the scope of this 1821 document and will vary on a case by case basis. Here are some 1822 options: 1824 1. A server may prevent the new node from being set if the old 1825 node is already set (and vice-versa). A "choice" 1826 construction could be used, or the new node may have a "when" 1827 statement to achieve this. The old node must not have a 1828 "when" statement since this would be an NBC change, but the 1829 server could reject the old node from being set if the new 1830 node is already set. 1832 2. If the new node is set and a client does a get or get-config 1833 operation on the old node, the server could use the value of 1834 the new node. For example, if the new node "ip-address" has 1835 value X then the server may return value X for the old node 1836 "ip-adress". 1838 4. When node "ip-adress" is not available anymore, its status is 1839 changed to "obsolete" and the "description" is updated. This is 1840 an NBC change. 1842 Authors' Addresses 1844 Robert Wilton (editor) 1845 Cisco Systems, Inc. 1847 Email: rwilton@cisco.com 1849 Reshad Rahman (editor) 1851 Email: reshad@yahoo.com 1853 Balazs Lengyel (editor) 1854 Ericsson 1856 Email: balazs.lengyel@ericsson.com 1858 Joe Clarke 1859 Cisco Systems, Inc. 1861 Email: jclarke@cisco.com 1863 Jason Sterne 1864 Nokia 1866 Email: jason.sterne@nokia.com